Menu
Is there a tool replacing javadoc with something that is more Wiki-style syntax instead of the HTMLish syntax of normal JavaDoc?
One of my problems is that I mostly read JavaDoc in source form. Even for external libraries I try to have the source attached so I can navigate into it from my IDE, checking the documentation above the entry point and if necessary the code below.
The other problem is that things like lists and code samples are messy to write, especially if your IDE insists on putting stars on every line. What I would like to see is something that uses a kind of Wiki syntax with at least the following features:
There are many more things that would be nice, but I believe these are the essentials.
Does anyone know of such a tool?
840
Fortunately, all modern versions of the JDK provide the Javadoc tool – for generating API documentation from comments present in the source code.
It's an annotation used so when you generate the Javadoc, you'll have a link for the specified item. In this case, the KeyEvent class, with the anchor of KEYCODE_ENTER.
This inserts an inline link with a visible text label. The text label points to the documentation for the specified package, class, or member name. This tag can be used everywhere, including an overview, package, class, method, field, etc.
The correct approach is an @param tag with the parameter name of <T> where T is the type parameter name. There should be one blank line between the Javadoc text and the first @param or @return. This aids readability in source code. The @param and @return should be treated as phrases rather than complete sentences.
There is a project called WikiDoclet, I have never used it, but I'd be interested to see what you think of it.
From the site:
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.
For other doclet formats, check out doclet.com.
150
now here: http://code.google.com/p/wikidoclet/
43
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
