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

Changes

• Version 1.0.3, Oct 5, 2003:
  Bulleted lists now may be created using tabs or spaces. If using spaces the depth of the list will be based on the number of spaces preceding the 1st item in the list. Also, the fixed font pattern =text= was breaking HTML tags embedded within javadoc. This has also been fixed. Thanks to Nicolas Carranza for pointing out the problems, and for sending me the source code to fix the issues.
  
  
• Version 1.0.2, Aug 1, 2003:
  This version is specifically to support changes to the javadoc api made in jdk 1.4.2 that are not backward compatible.
  
  
• Version 1.0.1, June 27, 2003:
  Bold *items* inside of bulleted lists (*) didn't work. The regex was replacing the entire line with <b></b> tags since the bold regex was applied before the bulleted list regex.

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:

• Wiki formatting replaces blank lines with paragraph tags so you no longer need to embed <p> tags in your source code.
• Bulleted lists may contain list items that span multiple lines.
• Bulleted lists may contain newlines between list items.
• Tables created by the |table| formatting rules have a css class of wikitable so that their style can be manipulated.
• The <pre> and <verbatim> tags support inline html without having to escape the tags.
• The <pre> and <verbatim> tags tags must be on a line by themselves.

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

ANT (1.2+)

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

H1

H4

• bullet1
  
  • bullet2
    
  • bullet3
    
    • bullet4
      more bullet4 text
      
  • bullet5
    
• bullet6
  
• bullet7
  
• bullet8 with bold
  
  

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

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