Skip to content

Commit

Permalink
Help page content updated.
Browse files Browse the repository at this point in the history
  • Loading branch information
@petrhosek
petrhosek committed Aug 9, 2011
1 parent 6bf6629 commit 0aa01fa
Showing 1 changed file with 89 additions and 20 deletions.
109 changes: 89 additions & 20 deletions src/main/scala/scala/tools/colladoc/page/Help.scala
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,48 +43,117 @@ class Help(rootPack: Package) extends scala.tools.colladoc.page.Template(rootPac
<div id="help_tabs">
<ul>
<li><a href="#help_about">About</a></li>
<li><a href="#help_edit">Editing</a></li>
<li><a href="#help_comments">Comments</a></li>
<li><a href="#help_discussions">Discussions</a></li>
<li><a href="#help_search">Search</a></li>
</ul>
<div id="help_about">
<h4>About:</h4>
<h2>Colladoc is a web application allowing to edit Scala symbols documentation.</h2>
<p>
Colladoc is web application allowing to edit Scala symbols documentation.
This application is based on existing Scaladoc 2 sources converted into full featured web application using the Lift web framework.
The application internally uses the documentation model constructed using Scala compiler frontend in the same way as Scaladoc 2 does.
</p>
<h4>Mergedoc integration:</h4>
<p>
The Colladoc web application also provides REST interface which provide access to the collected comments. <br />
This allows to export the changes and merge them into original source code. <br />
Mergedoc sources you can find at <a href="https://github.com/colladoc/mergedoc" class="link">GitHub</a>.
The interface of this web application is extended in order to allow wiki-like editing of Scala symbol comments.
Application also allows to show different versions of documentation related to single symbol for each users together
with displaying history of all changes in the form of aggregated timeline.
</p>
<h4>Helpful links:</h4>
<p>
The <b>Colladoc</b> web application also provides REST interface which provide access to the collected comments.
This allows to export the changes and merge them into original source code.
</p>
<p>
The <b>Mergedoc</b> application is a command-line tool reimplementing the functionality of scaladoc-merge tool providing same features.
The application allows to merge changes exported from the Colladoc web application to directly to source codes.
</p>
<p>
<h3>Useful links:</h3>
<ul>
<li><a href="http://colladoc.github.com/" class="link">Official site</a></li>
<li><a href="http://colladoc.posterous.com/" class="link">Official blog</a></li>
<li><a href="https://github.com/colladoc/colladoc" class="link">Sources</a></li>
<li><a href="https://github.com/colladoc/colladoc/wiki" class="link">Wiki</a></li>
</ul>
</p>
</div>
<div id="help_edit">
<h3>Regular users</h3>
<div id="help_comments">
<h2>Browsing</h2>
<p>
Colladoc allows registered users edit comments for existing entities.
Colladoc application is based upon <a href="http://www.scala-lang.org/api">Scaladoc</a>.
Therefore, basic functionality, such is browsing documentation works in the exactly same way.
Moreover, this functionality is similar to other well-known tools such as <a href="http://download.oracle.com/docs/cd/E17409_01/javase/6/docs/api/">Javadoc</a>.
</p>
<h3>Superusers</h3>
<h2>Editing</h2>
<p>
Colladoc allows superusers:
<ul>
<li>Edit comments for existing entities.</li>
<li>Delete comments for existing entities.</li>
<li>Propagate comments in hierarchy.</li>
<li>Select the default comment from the comment list.</li>
</ul>
Colladoc allows you to edit comments for any symbol.
To edit the comment, you need to use the edit mode for selected symbol which can be switched by clicking the edit link.
This will replace the symbol comment with inline editor which can be used to edit the comment (or even create in case the symbol has no comment).
Finally, you may choose to submit or cancel the changes. <em>Note that you have to be logged in to edit the comments.</em>
</p>
<div>
<h3>Regular users</h3>
<p>
Registered users can edit comments for existing symbols.
</p>
<h3>Superusers</h3>
<p>
Furthermore, superusers are allowed to:
<ul>
<li>edit and delete comments for existing symbols,</li>
<li>propagate comments in symbols hierarchy,</li>
<li>select the default revision for each symbol comment.</li>
</ul>
</p>
</div>
<h2>Exporting</h2>
<p>
Comment changes may be exported in the XML format used by scaladoc-merge tool.
This tool allows you to merge the changed comments into the original source code.
To export the changes, click the export link.
</p>
<p>
The Scaladoc merge tool can be installed in Eclipse using this update site.
Once installed, context-click on the project containing the documentation you want to update, and choose "Merge Scaladoc...".
</p>
<h2>History</h2>
<p>
History of all changes can be seen for every symbol. Previous versions of each change can be seen, edited and exported.
</p>
<p>
The history page contains the timeline of all changes done in selected time-frame.
Moreover this may be filtered according to selected to user.
The aggregation is used so that changes done by one user in short time-frame will be displayed as one.
</p>
</div>
<div id="help_discussions">
<h2>Discussions</h2>
<p>
Colladoc allows you to add additional content in the form of discussions, similar to discussions known from blogs and other websites.
Not only allow you this functionality to submit related content, it also allows you to ask/answer questions and propose improvements to existing content.
</p>
<p>
Discussion section is available for each top-level symbol (i.e. packages, classes, objects and traits) and is collapsed by default.
</p>
<h2>Categories</h2>
<p>
Discussion content is divided into categories. These are pre-defined globally for the application.
Each category may have different policy, specifying whether anonymous users are allowed to see and/or edit its content.
</p>
<p>
Categories and their policies can be managed onyl by superusers.
</p>
</div>
<div id="help_search">
<h3>Here are some sample queries to get you started:</h3>
<p>
The search functionality provides a full-text search capabilities making it possible to search for identifiers, symbols and documentation comments.
This functionality provides powerful query syntax that resembles the Scala language.
</p>
<p>
Search queries can be entered using the search box. Relevant search results are presented on a separate search page.
This page uses infinite scrolling to asynchronously load additional results when needed.
</p>
<div>
<h3>Sample queries to get you started:</h3>
<ul class="search_example_list">
<li><a target="template" href="/search?q=any" >any</a>
searches for everything that has the word any in its name, definition or comment
Expand Down

0 comments on commit 0aa01fa

Please sign in to comment.