WikiDoclet
(wiki formatting for javadoc)
Jason Horman (jason@jhorman.org)

JDK 1.4.2
Complete Distribution for jdk 1.4.2 (UNIX): dist/wikidoclet.1.0.3.tar.gz
Complete Distribution for jdk 1.4.2 (Windows): dist/wikidoclet.1.0.3.zip
Jar: dist/lib/wikidoclet.1.0.3.jar

JDK pre-1.4.2
Complete Distribution (UNIX): dist/wikidoclet.1.0.1.tar.gz
Complete Distribution (Windows): dist/wikidoclet.1.0.1.zip
Jar: dist/lib/wikidoclet.1.0.1.jar

Javadocs: target/docs/javadoc/index.html
Text Formatting Rules: TWikiTextFormattingRules.htm

Changes

Description

This is an extension to the standard javadoc doclet provided with the Java JDK. It adds support for what I am calling Wiki formatting. What this means is that your JavaDoc can now be formatted using text rules that are easier on the eyes than html embedded in JavaDoc. For example, to put emphasis on a piece of text you surround it with *stars*. Italics with _underscores_. When the doclet is run to produce JavaDoc these rules are evaluated and html substitutions are made. This formatting should make reading java source code much easier since it will no longer be cluttered with HTML tags. This is especially true for bulleted lists and for tables. HTML is preserved still though, so you can mix and match as you like.

The text formatting rules were taken from rules defined by TWiki and work the same for the most part.

Formatting Notes:

All aspects of JavaDoc are supported by WikiDoclet, method comments, class comments, package comments, param comments, etc.

See the package.html of the wikidoclet package for an example of Wiki formatting in use.

Usage

Command line

javadoc -docletpath /path/to/wikidoclet.1.0.1.jar -doclet wikidoclet.WikiDoclet [packagenames] [sourcefiles] ...

ANT (1.2+)

  <javadoc doclet="wikidoclet.WikiDoclet" docletpath="path/to/wikidoclet.1.0.1.jar"/ >
        ...
  </javadoc>

Examples

Example Javadoc Comment

    /**
     * Generates the =HTML= for the =wikidoclet= class.
     * *NOTE*: This method is not threadsafe.
     *
     * Todo:
     *    * Write a new _faster_ version
     *    * Deprecate this version
     */

All Wiki Supported Shorthand

Test normal
Test newline

Test *bold*
Test _Italic_
Test __BoldItalic__
Test ---+ H1
Test ---++++ H4
Test =fixed font=
Test ==bold fixed font==
Test horiz line ---------
Test bullets

   * bullet1
      * bullet2
      * bullet3
         * bullet4
           more bullet4 text

           again more bullet4 text

       * bullet5
   * bullet6
   * bullet7
   * bullet8 with *bold*

Test numbered bullets

   1. bullet1
      1. bullet2
   1. bullet3
   1. bullet4
   1. bullet5 with *bold*

Test table

  |*h1*|*h2*|*h3*|
  |1|2|3|

  | *h1* | *h2* | *h3* |
  | 1 | 2 | 3 |

  |  *header1* | *header2* | *header3*  |
  |  1 | 2 | 3  |

<verbatim>
foreach item (items) {
   do();
   print("<br>&&<br>");
}
</verbatim>

Generated HTML From Shorthand Above

Test normal
Test newline

Test bold
Test Italic
Test BoldItalic
Test

H1

Test

H4

Test fixed font
Test bold fixed font
Test horiz line

Test bullets

Test numbered bullets

  1. bullet1
    1. bullet2
  2. bullet3
  3. bullet4
  4. bullet5 with bold

Test table

h1 h2 h3
1 2 3

h1 h2 h3
1 2 3

header1 header2 header3
1 2 3

foreach item (items) {
   do();
   print("<br>&&<br>");
}

License

Copyright (C) 2003  Jason Horman (jason@jhorman.org)

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA

Sun Microsystems License

This is a derivitive work based on Sun's standard doclet. I followed the instructions for "modifying the standard doclet".