<html><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>BshDoc - Javadoc Style Documentation</title></head><body bgcolor="ffffff"><table cellspacing="10"><tr><td align="center"><a href="http://www.beanshell.org/"><img src="../images/homebutton.gif"><br>Home</a></td><td><a href="desktop.html#BeanShell_Desktop"><img src="../images/backbutton.gif"><br>Back
</a></td><td align="center"><a href="contents.html"><img src="../images/upbutton.gif"><br>Contents</a></td><td align="center"><a href="parser.html#The_BeanShell_Parser"><img src="../images/forwardbutton.gif"><br>Next
</a></td></tr></table><h1>BshDoc - Javadoc Style Documentation</h1>
<em>BshDoc requires JDK1.4 and BeanShell 1.2b6 or greater to run</em>
<p CLEAR="ALL"></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 CLEAR="ALL"></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 CLEAR="ALL"></p>
<h2><a name="BshDoc_Comments">BshDoc Comments</a></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.
<p></p><center><table width="100%" cellpadding="5" border="1"><tr><td bgcolor="#dfdfdc"><pre>
/**
This is a javadoc style comment.
<pre>
<b>Here is some HTML markup.</b>
<p/>
Here is some more.
</pre>
@author Pat Niemeyer
*/
</pre></td></tr></table></center><p></p>
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 CLEAR="ALL"></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 CLEAR="ALL"></p>
<h2><a name="BshDoc_XML_Output">BshDoc XML Output</a></h2>
To use BshDoc, run the bshdoc.bsh script on one or more BeanShell script
files:
<p></p><center><table width="100%" cellpadding="5" border="1"><tr><td bgcolor="#dfdfdc"><pre>
java bsh.Interpreter bshdoc.bsh myfile.bsh [ myfile2.bsh ] [ ... ] > output.xml
</pre></td></tr></table></center><p></p>
The output goes to standard out. It looks something like this:
<p></p><center><table width="100%" cellpadding="5" border="1"><tr><td bgcolor="#dfdfdc"><pre><!-- 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></pre></td></tr></table></center><p></p>
<h2><a name="The_bshcommands.xsl_stylesheet">The bshcommands.xsl stylesheet</a></h2>
The bshcommands.xsl stylesheet can be used to render the output of bshdoc.bsh
to an indexed HTML page describing BeanShell commands.
<p CLEAR="ALL"></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 CLEAR="ALL"></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 CLEAR="ALL"></p>
<p></p><center><table width="100%" cellpadding="5" border="1"><tr><td bgcolor="#dfdfdc"><pre>
/**
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 ) { ... }
</pre></td></tr></table></center><p></p>
<p></p><center><table width="100%" border="1" cellpadding="5"><tr><td><strong>Tip:</strong><br CLEAR="ALL">
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.
</td></tr></table></center><p></p>
<table cellspacing="10"><tr><td align="center"><a href="http://www.beanshell.org/"><img src="../images/homebutton.gif"><br>Home</a></td><td><a href="desktop.html#BeanShell_Desktop"><img src="../images/backbutton.gif"><br>Back
</a></td><td align="center"><a href="contents.html"><img src="../images/upbutton.gif"><br>Contents</a></td><td align="center"><a href="parser.html#The_BeanShell_Parser"><img src="../images/forwardbutton.gif"><br>Next
</a></td></tr></table></body></html>
