BshDoc - Javadoc Style Documentation

BshDoc requires JDK1.4 and BeanShell 1.2b6 or greater to run

BshDoc is a BeanShell script that supports supports javadoc style documentation of BeanShell scripts. BshDoc parses one or more BeanShell script files for method information and javadoc style formal comments. Its output is an XML description of the files, containing all of the method signature and comment information.

An XSL stylesheet, bshcommands.xsl, supplied with the user manual source, can be used to render the XML to a nicely indexed HTML document describing BeanShell commands.

The bshdoc.bsh script is currently distributed with the source distribution. An example of the styled output of this command is the BeanShell Commands Documentation section of this user manual. That section is automatically generated as part of the build process by running bshdoc.bsh on bsh/commands/*.bsh. See the source distribution Ant build file for an example of how to do this and the user manual Ant build file for an example of using a stylesheet to build your documents.

BshDoc comments look just like JavaDoc comments and may include HTML markup and javadoc style @tags. If you wish to use the associates XSL stylesheet, you should use well formed XHTML for you documentation. (Always close tags, etc.). e.g.

/**
    This is a javadoc style comment.
    <pre>
        <b>Here is some HTML markup.</b>

        Here is some more.
    </pre>

    @author Pat Niemeyer
*/

Javadoc style @tags are parsed by bshdoc for inclusion in the XML output.
Currently they are only recognized at the start of a line and they terminate the comment. (i.e. they must come at the end of the comment).

BshDoc identifies two kinds of Javadoc style comments: File Comments and Method Comments.

Method comments are comments that appear immediately before a method declaration with no statements intervening.

File comments are comments that appear as the first statement of a script and are not method comments. If a comment appears as the first statement in a script and is also immediately followed by a method declaration it is considered a method comment.

To use BshDoc, run the bshdoc.bsh script on one or more BeanShell script files:

java bsh.Interpreter bshdoc.bsh myfile.bsh [ myfile2.bsh ] [ ... ] > output.xml

The output goes to standard out. It looks something like this:

<!-- This file was auto-generated by the bshdoc.bsh script -->
<BshDoc>
  <File>
    <Name>foo</Name>
    <Method>
      <Name>doFoo</Name>
      <Sig>doFoo ( int x )</Sig>
      <Comment>
        <Text>&lt;![CDATA[ doFoo() method comment. ]]&gt;</Text>
        <Tags>
        </Tags>
      </Comment>
    </Method>
    <Comment>
        <Text>&lt;![CDATA[ foo file comment. ]]&gt;</Text>
        <Tags>
        </Tags>
    </Comment>
  </File>
</BshDoc>

The bshcommands.xsl stylesheet can be used to render the output of bshdoc.bsh to an indexed HTML page describing BeanShell commands.

The bshcommands.xsl stylesheet is intended for scripts that serve as BeanShell commands. These are script files containing one or more overloaded methods which have the same name as the filename containing them.

The BshDoc script produces a complete description of any BeanShell script file. However the supplied bshcommands.xsl stylesheet does not necessarily use all of this information. Specifically, it does not present all individual method comments. Instead it tries to identify the comments pertaining to the command, based upon the file name. It (the XSL stylesheet) applies some logic to choose either the single File Comment if it exists or the Method Comment of the first method matching the filename. Another stylesheet could (and will) be easily created for more general BeanShell file documentation. Please check the web site for updates.

Method signatures displayed for methods can be overridden for the bshcommands.xsl stylesheet by explicitly supplying them in special javadoc @method tags within a Method Comment. For example you might do this to provide a more verbose description for loosely typed arguments to a BeanShell command.
The bshcommands.xsl stylesheet will use the @method tag signatures in lieu of autogenerated ones when they are present. So you can also use this tag to determine exactly which methods from a file are listed if you wish. e.g.

/**
    BshDoc for the foo() command.
    Explicitly supply the signature to be displayed for the foo() method.

    @method foo( int | Integer ) and other text...
*/
foo( arg ) { ... }

Tip: BshDoc uses the bsh.Parser API to parse the BeanShell script files without actually running them. bshdoc.bsh is not very complex. Take a look at it to learn how to use the parser API.