I’ve spent a little time pulling apart the DSL documentation plugins in the gradle source. They are very clever, but also quite complex. Custom parsers for groovy classes, extracting javadoc and other data. Then conversion of the html and javadoc tags into docbook and merging the result into some very sparse docbook templates. Finally a traditional docbook to html conversion process.
I’m thinking of doing something similar, because I’m bumping into the limits of what is easily achieved with doclets to customise Javadoc output. But I’m concerned about some parts of the gradle approach:
- javadocs limited to simplified html rather than more expressive docbook
- how fragile the html/javadoc to docbook conversion process might be (whether you are often chasing bugs with unusual syntax)
- why do you have those almost empty docbook files instead of just generating the whole thing?
If you had to do this all again from scratch, would you build it all again the same way? Or would it be simpler to write directly in docbook and deal with the separation between code and documentation (and the resulting errors that might occur).
If you still believe this to be a really solid approach, do you still have plans to turn the javadoc -> docbook part into a plugin?
Or, would it be valuable to explore ways to customise the javadoc doclets? In theory Java already has a whole framework for parsing classes, extracting metadata and handling the specialised html markup in javadocs. Was it just easier to write all that again rather than deal with doclets?
Thanks in advance for any insights you can provide on your fascinating documentation workflow.