<section>
<name filename="bshdoc">BshDoc - Javadoc Style Documentation</name>

<em>BshDoc requires JDK1.4 and BeanShell 1.2b6 or greater to run</em>
<p/>

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.
<p/>

The bshdoc.bsh script is currently distributed with the 
<a href="http://www.beanshell.org/developer.html">source distribution</a>.
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.
<p/>

<h2>BshDoc Comments</h2>

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.

<example><![CDATA[ 
/**
    This is a javadoc style comment.
    <pre>
        <b>Here is some HTML markup.</b>
        <p/>
        Here is some more.
    </pre>

    @author Pat Niemeyer
*/
]]></example>

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).
<p/>

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 
<b>and</b> 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.
<p/>


<h2>BshDoc XML Output</h2>

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

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

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

<example><![CDATA[<!-- 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>]]></example>

<h2>The bshcommands.xsl stylesheet</h2>

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

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.

<p/>
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.
<p/>

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

<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.
</tip>

</section>
