Generating your own API documentation

at 2009-06-07 in Examples by friebe (0 comments)

Screenshot To generate api documentation for your project or library, a new project inside XP Forge has been started. It will - like the JavaDoc tool - generate documentation from apidoc comments inside your classes' sourcecode into browseable HTML pages. On the right hand side, you can see an example of the generated HTML.

Features:

A package overview pages shows interfaces, classes, enums, exceptions and errors summary
For interfaces, implementing classes are listed
For classes, all direct subclasses are shown
Markup in apidoc comments is recognized and displayed
The output is styleable via CSS

Note: To use this generator, you must be using an up-to-date source checkout of both xp framework and xp forge or wait for the upcoming 5.7.3 release which will include this.

Example command line:
The following was used to produce the documentation the example screenshot comes from:

  $ doclet \
    -cp ~/devel/xp.forge/trunk/projects/textproc/apidoc/src \
    -sp ~/dialog/dialog-2.4.2.xar:~/devel/xp.public/trunk/skeleton' \
    net.xp_forge.apidoc.Doclet \
    de.thekid.** \ 
    -output ~/apidoc/gen/dialog \
    -api 'Dialog 2.4.2' \
    -css ~/devel/xp.forge/trunk/projects/textproc/apidoc/styles/default.css \
    -gen 'Generated at 2009-06-07'

This is quite a bit of text - you might think - and you're right

Let's go through the options one by one:

-cp [...]: Add the .../projects/textproc/apidoc/src directory to the classpath
-sp [...]: Sets the source path - that is, the path that the doclet will search for classes in
net.xp_forge.apidoc.Doclet: The doclet's class name
de.thekid.**: Instructs the doclet to process all classes inside the package de.thekid and all of its subpackages
-output [...]: Sets the output path where the documentation files should be written to
-api [...]: Sets the API to be documented, will appear in the overview page and the page titles of all generated pages
-css [...]: Tells the generator to embed the given CSS file into all generated pages
-gen [...]: Sets a generator comment, will appear in the footer of all generated pages

Happy documenting!

You can subscribe to the XP framework's news by using RSS syndication.

Generating your own API documentation

Subscribe

Categories

Related