/[classpath]/gjdoc/docs/invoke.texi
ViewVC logotype

Diff of /gjdoc/docs/invoke.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.1 by julian, Thu Feb 10 16:06:16 2005 UTC revision 1.2 by julian, Thu Feb 17 15:10:46 2005 UTC
# Line 1095  Missing. Line 1095  Missing.
1095  @chapter Advanced Concepts  @chapter Advanced Concepts
1096    
1097  @menu  @menu
1098    * Writing Doclets::
1099  * Taglets::  * Taglets::
1100  * XHTML Fragments::  * XHTML Fragments::
1101  * First Sentence Detector::  * First Sentence Detector::
# Line 1104  Missing. Line 1105  Missing.
1105    
1106  @node Taglets  @node Taglets
1107  @section Adding Custom Tags to the Documentation  @section Adding Custom Tags to the Documentation
1108  @cindex Doclet  @cindex Taglet
1109    
1110  Missing.  Missing.
1111    
1112    @node Writing Doclets
1113    @section Writing Doclets
1114    @cindex Taglet
1115    
1116    If the various Doclets already available don't suit your needs, you
1117    can write a custom Doclet yourself.  
1118    
1119    @menu
1120    * Doclet Invocation Interface::
1121    * Using AbstractDoclet::
1122    * GNU Doclet SPI::
1123    @end menu
1124    
1125    @node Doclet Invocation Interface
1126    @subsection Implementing the Doclet Invocation Interface
1127    
1128    A Doclet is a class that contains a method with the following
1129    signature:
1130    
1131    @smallexample
1132    public static boolean start(RootDoc rootDoc);
1133    @end smallexample
1134    
1135    @var{rootDoc} is the root of an object hierarchy containing the
1136    information @command{gjdoc} extracted from the source files.  See the
1137    Doclet API for more details.
1138    
1139    @samp{start} should process all the information and return
1140    @samp{true} on success, @samp{false} on failure.
1141    
1142    For printing status information, the Doclet should use methods
1143    @samp{printNotice}, @samp{printWarning} and @samp{printError} instead
1144    of @samp{System.err}.  The Doclet can opt to use @samp{System.out} for
1145    redirectable output.
1146    
1147    @node Using AbstractDoclet
1148    @subsection Deriving Your Doclet from AbstractDoclet
1149    @cindex AbstractDoclet
1150    
1151    You may want your Doclet to provide functionality similar to
1152    HtmlDoclet.  For example, you may want it to support Taglets, generate
1153    Index, Tree, and Uses pages, or show other cross-reference information
1154    like @samp{Overrides} and @samp{All Implementing Classes}.
1155    
1156    This information is not directly provided by the Doclet API, so your
1157    Doclet would normally have to assemble it itself.  For example, it
1158    would have to add the names of all program elements to a list and sort
1159    this list in order to create the Index page.
1160    
1161    If you want to provide this information or part of it, you should
1162    consider deriving your class from
1163    @samp{gnu.classpath.tools.doclets.AbstractDoclet}.  This class
1164    provides the following benefits:
1165    
1166    @itemize @bullet
1167    
1168    @item
1169    Handles options @option{-tag}, @option{-taglet}, @option{-tagletpath}
1170    (Taglets)
1171    
1172    @item
1173    Provides standard taglets for @@version, @@author, @@since, @@serial,
1174    @@deprecated, @@see, @@param, @@return and handles all related options
1175    (@option{-version}, @option{-author}, @option{-nosince},
1176    @option{-nodeprecated})
1177    
1178    @item
1179    Handles option @option{-d} (destination directory)
1180    
1181    @item
1182    Handles option @option{-noqualifier} (classes to omit qualifier for)
1183    
1184    @item
1185    Handles options @option{-docfilessubdirs} and
1186    @option{-excludedocfilessubdir} (resource copying)
1187    
1188    @item
1189    Can generate a full index or an index split by first letter
1190    
1191    @item
1192    Can generate a full tree and package trees
1193    
1194    @item
1195    Can generate cross-reference information
1196    
1197    @item
1198    Can aggregate interface information (all superinterfaces, all
1199    subinterfaces, all implementing classes)
1200    
1201    @item
1202    Provides convenient access to constructors, fields, methods, and inner
1203    classes sorted by name/signature instead of the default sort order.
1204    
1205    @item
1206    Provides various other convenience methods
1207    
1208    @end itemize
1209    
1210    If you derive from @samp{AbstractDoclet}, there are a number of things
1211    you need to take care of:
1212    
1213    @itemize @bullet
1214    
1215    @item
1216    
1217    @end itemize
1218    
1219    you should not implement the
1220    @samp{start(RootDoc)} method as it is already defined by
1221    @samp{AbstractDoclet} so that it can care about parsing the options.
1222    
1223    Instead, you implement method @samp{run()}, @samp{getOptions()} and
1224    the other abstract methods to define your Doclet's behavior.
1225    
1226    Note that all information provided by @samp{AbstractDoclet} is
1227    evaluated lazily.  That is, if your Doclet doesn't need to create an
1228    Index page, then @samp{AbstractDoclet} will not spend resources on
1229    creating the corresponding information.
1230    
1231    See the API documentation for
1232    @samp{gnu.classpath.tools.doclets.AbstractDoclet} for more details.
1233    
1234    You should be aware that if you base your Doclet on
1235    @samp{AbstractDoclet} then you have to bundle this and all related
1236    classes with your Doclet, with all implications such as possible
1237    licensing issues.  Otherwise, your Doclet will only be runnable on
1238    @samp{gjdoc} and not on other documentation systems.  Also note that
1239    @samp{AbstractDoclet} has not been extensively tested in environments
1240    other than @samp{gjdoc}.
1241    
1242    @node GNU Doclet SPI
1243    @subsection Preparing for the GNU Doclet Service Provider Interface
1244    @cindex GNU Doclet SPI, Service Provider, SPI
1245    
1246    In addition to the standard Doclet invocation interface described
1247    above, @command{gjdoc} also offers a Service Provider Interface
1248    conforming to the Java standard.  Adding support for this interface to
1249    your Doclet simplifies usage for @command{gjdoc} users because it
1250    makes your Doclet ``discoverable''.
1251    
1252    In order to provide the alternate interface, you have to add a class
1253    implementing @samp{gnu.classpath.tools.gjdoc.spi.DocletSpi} to your
1254    Doclet classes, and bundle all Doclet classes in a Jar file along with
1255    a file named
1256    @samp{META_INF/services/gnu.classpath.tools.gjdoc.spi.DocletSpi} which
1257    contains the name of your class implementing DocletSpi on a single
1258    line.
1259    
1260    Note that if your Doclet depends on third-party classes bundled in
1261    separate Jar files, you can link in these classes using the
1262    @samp{Class-path:} Manifest attribute of your Doclet Jar.
1263    
1264    Your Doclet can then be invoked in one of the following ways:
1265    @smallexample
1266    gjdoc -docletjar /path/to/doclet.jar
1267    gjdoc -docletpath /path/to/doclet.jar -docletname @var{docletname}
1268    gjdoc -docletname @var{docletname}
1269    @end smallexample
1270    
1271    Here, @var{docletname} is the name of your doclet as returned by
1272    @samp{DocletSpi.getDocletName()}.
1273    
1274    The last example will only work if your Doclet Jar is in
1275    @command{gjdoc}'s @file{doclets} directory or if it is on the
1276    classpath.
1277    
1278  @node XHTML Fragments  @node XHTML Fragments
1279  @section Well-formed Documentation Fragments  @section Well-formed Documentation Fragments
1280  @cindex XHTML Fragments  @cindex XHTML Fragments
1281    
1282  Missing.  For many Doclets it is advantagous if the HTML code in the comments
1283    and HTML code passed via the command line is well-formed.  For
1284    example, HtmlDoclet outputs XHTML code, and XmlDoclet XML code, both
1285    of which results in invalid files if the user-specified HTML isn't
1286    wellformed.
1287    
1288    Unfortunately, comments were never required to contain well-formed
1289    HTML code, which means that every Doclet must deal with non-wellformed
1290    code as well.
1291    
1292    The @command{gjdoc} built-in Doclets deal with this problem by
1293    ``fixing'' the HTML code - making sure that all tags are closed,
1294    attribute values are provided and quoted, tags are properly nested,
1295    etc.
1296    
1297    This approach works OK in most instances, but since it uses some crude
1298    heuristics it can sometimes produce undesirable result.
1299    
1300    Therefore, in order to make sure that your comments are always
1301    properly formatted, make sure they are well-formed as described in
1302    @w{@uref{http://www.w3.org/TR/xhtml1/#h-4.1, XHTML 1.0: Documents must
1303    be well-formed}}.
1304    
1305    In addition, you should use meaningful tags instead of text formatting
1306    tags to make your output look better in other output formats derived
1307    from your HTML code.  For example, you should use the <em> tag instead
1308    of <b> if you want to emphasize text.
1309    
1310  @node First Sentence Detector  @node First Sentence Detector
1311  @section How Gjdoc Determines where the First Sentence Ends  @section How Gjdoc Determines where the First Sentence Ends
1312  @cindex First Sentence Detector  @cindex First Sentence Detector
1313    
1314    For a package, class or member summary, @command{gjdoc} only shows the
1315    first sentence of the documentation comment in question.  Because
1316    @command{gjdoc} is not human, it is not always obvious to
1317    @command{gjdoc} where the first sentence ends.
1318    
1319    You might be tempted to say that the first sentence ends at the first
1320    occurrence of a punctuation character like @samp{.} or
1321    @samp{!}. However, consider examples like this:
1322    @smallexample
1323    This work, by Thomas J. Shahan et al., is about the middle ages.
1324    @end smallexample
1325    
1326    As you can see, it is not trivial to determine the end of the
1327    sentence.
1328    
1329    @command{gjdoc} gives you the choice between two approaches.  By
1330    default it uses built-in heuristics which should be compatible to
1331    Sun's @command{javadoc} tool.  This approach works quiet well in most
1332    cases, at least for english comments.
1333    
1334    Alternatively, you can specify option @option{-breakiterator} in which
1335    case @command{gjdoc} will use
1336    @samp{java.text.BreakIterator.getSentenceInstance(@var{locale}).next()}
1337    to find the end of sentence, where @var{locale} is the locale
1338    specified by option @samp{-locale} or the default locale if none
1339    specified.
1340    
1341    @emph{NOT YET IMPLEMENTED:}
1342    
1343    @command{gjdoc} also allows you to explicitly delineate the first
1344    sentence by putting it in a @samp{<span>} tag with the CSS class
1345    @samp{first-sentence}.  For example:
1346    @smallexample
1347    /**
1348     *  <span class="first-sentence">This. is. the. first.
1349     *  sentence.</span> This is the second sentence.
1350     */
1351    @end smallexample
1352    
1353    Note that this will only work with @command{gjdoc}, but shouldn't hurt
1354    when using another documentation system since the @samp{<span>} tag
1355    usually doesn't show up in the output.
1356    
1357  @node Adding Custom Resources  @node Adding Custom Resources
1358  @section Adding Images and Other Resources  @section Adding Images and Other Resources
1359  @cindex First Sentence Detector  @cindex First Sentence Detector
1360    
1361  Missing.  Sometimes you want to decorate your documentation with secondary
1362    resources such as images, SVG graphics, applets, and so on.  To do so,
1363  @c @node Abusing the Doclet API  simply put the required files in a subdirectory 'doc-files' in the
1364  @c @chapter Using the Doclet API for Other Purposes  package directory corresponding to the documentation entry you want to
1365    decorate, and refer to it with the URL
1366  @c @node Creating Doclets  @samp{doc-files/@var{filename}}.
1367  @c @chapter Creating New Doclets  
1368    For example, if you want to add an image to the description of class
1369    @samp{baz.FooBar}, create a directory @file{doc-files} in the
1370    directory @file{baz} containing @file{FooBar.java} and put your file,
1371    say @file{diagram.png}, into that directory.  Then, add the HTML code
1372    like this to a comment in @file{FooBar.java}:
1373    @smallexample
1374    <img src="doc-files/diagram.png" width="200" height="150"
1375      alt="Foo Diagram"/>
1376    @end smallexample
1377    
1378    This works because the @file{doc-files} subdirectories will be copied
1379    to the target documentation directory every time you generate the
1380    documentation.  
1381    
1382    Note however that by default, the @file{doc-files} directory will not
1383    be copied deeply.  In other words, if you create subdirectories under
1384    @file{doc-files} they will not be copied and any resources located in
1385    these subdirectories will not be accessible in your generated
1386    documentation.  You can specify option @option{-docfilessubdirs} to
1387    remove this limitation.
1388    
1389    Sometimes you want to use option @option{-docfilessubdirs}, but there
1390    are certain directories which you don't want to be copied, for example
1391    because they contain source files for the resources in
1392    @file{doc-files}.  For cases like this, use
1393    @option{-excludedocfilessubdir} to specify directories to be omitted.
1394    
1395  @c       --version        @c       --version      
1396  @c       -help, --help  @c       -help, --help

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26