Home

Back

Contents

Next

BshDoc - Javadoc Style Documentation

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

 
/**
    This is a javadoc style comment.
    <pre>
        <b>Here is some HTML markup.</b>
        <p/>
        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.

BshDoc XML Output

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

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 ) { ... }

Home

Back

Contents

Next