HelmaDoc: Documenting Helma Applications

Helma applications can be documented in a way similiar to java code. Add comments to your functions and generate HTML Apidoc with the manage application.

Add comments to all your functions and macros in javadoc style like this:

/**
* this function is here to do this and that ...
* you may also use <b>html</b> tags
* @param nameOfTheParam you can use special tags here
*/
function testfunction (nameOfTheParam) {
// so do something
}

Comments of actions in .hac files looks just the same and has to be at the very top of the file. Because of the way the javascript parser in helma works there must not be another comment before the first "real" javascript code starts. At the moment skin files can't be documented.

To add comments to a prototype or an application add a file called doc.html or index.html to the specified directory. Its content will be parsed, javascript comment tags will be chopped away.


Usage of tags
You can use a number of tags that are common to many comments and formatted in different ways in the resulting HTML.

• @param describes a parameter, the first word of the text is considered as its name. Parameters are used in different ways: For functions its obvious, for macros the accepted values of the param-object need to be described, for actions the http-parameter in req.data. E.g.
  
@param nameOfTheParam further description ...
@param par.paramName if you describe a macro
@param req.data.paramName if you describe an action

• @return describes the return value of a function.
• @author name of the author (all elements)
• @version version string (all elements)
• @deprecated marks a function as deprecated. It should not be used anymore but stays in the application for backwords compatibility.
• @see tries render a link. If the rest of the tag starts with "http://" the tag is rendered as an URL. To show a link to another element within the application you can specify a prototype or a combination of prototype.function. Further comment may follow that definintion:

  @see http://www.antville.org
  @see myPrototype more description
  @see myPrototype.myFunction more description
  

• @overrides allows to link to other parts of the application in the same syntax as the @see tag. This tag should especially be used if a method is overridden that can't be found in the application at hand - because it is included in a zip-file or the application has a custom class-mapping and javascript functions override methods of the underlying java object.

... comment

Page last modified on 2002-11-22 15:15 by czv