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:: |
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 |