proxy-doclet
by infinity0 <infinity0@freenetproject.org>

license is GPL 2 with Sun's classpath exception, as described in LICENSE

This package implements some patches to Sun's Standard Java Doclet to attach
various hooks to certain operations, and allow the user to specify custom
actions to modify the operation of the doclet.

So far, the supported hooks are:

- when rendering the javadoc comment text to HTML

and the supported actions are:

- parse the text as MediaWiki markup
- parse the text as pandoc markdown

I originally wanted a doclet that could allow me to use MediaWiki syntax in
javadoc comments, because having to type <p> everywhere is tedious and ugly.
Many people have implemented doclets that do similar things, but most of these
revolved around copying and editing the source for the Standard Java Doclet.

This isn't flexible or extensible, and I've taken a different approach here. I
do modify the Standard Java Doclet, but only in a minimal way, and the rest of
the extended functionality is implemented in separate adapter classes. OOP
after all, is supposed to increase reusability and modularity.

The major advantage with this approach is that it's very easy to add new
features, such as support for different markup languages, and potentially add
hooks to other parts of the operation of the doclet, whilst maintaining a
relatively distinct separation from the Standard Java Doclet source code.


## Dependencies

Put these in lib/:

* bliki-core.jar http://code.google.com/p/gwtwiki/

Install these programs:

* pandoc http://johnmacfarlane.net/pandoc/


## Build

The build script will automatically detect your version of Java and build
against the appropriate version of the Standard Java Doclet using the source
code in src.orig/ - so the following should work "out-of-the-box":

$ ant

If you want to specify a custom path to the source code:

$ ant -Dsrc.orig=/path/to/source

(Note that in this case, you also need to have the full set of doclet-related
classes in your classpath, version-compatible with your custom source code.)

## Use

Ant:

	<javadoc>
		<doclet name="proxy.doclets.standard.Standard" path="path/to/proxy-doclet.jar"/>
		<arg value="[FLAG]"/>
		<arg value="-J-D[KEY]=[VALUE]"/>
	</javadoc>

[FLAG] takes all the values that the standard doclet takes (`javadoc -help`).

[KEY] is a java system property name. proxy-doclet uses the following:

proxy.adapters.markup={pre|pandoc*|mediawiki} *default
	indicates the proxy to use
proxy.adapters.pandoc.cmdline=*
	space-separated string to execute as pandoc command. you can escape the
	spaces with \; double-escaping (\\ -> \) also works correctly.
proxy.doclets.keeptabs={true|false}
	whether to keep tabs in the source code