Is there a way to include body comments in javadocs?

Question

We've got a large codebase of Java (with a smattering of Groovy mixed in) that, by and large, has no javadocs written for it.

However, much of the code is reasonably well documented in "old-school" comments scattered throughout the body.

We're now on something of a push to try and get things documented a little better - Javadocs are now being generated on a regular basis, for example. As a stopgap measure, it would be really nice if javadoc would "scrape" the body of the class (or function, or whatever) and toss all the comments within into a "stub" javadoc.

Is there a way to do that?

Answer 1

Sounds like a bad idea, given that javadocs typically describe purpose and usage of elements, and code body comments are (or should be) about the details of implementation.

But if you must, you clearly need to write your own custom doclet that works in concert with a java source file parser (either 3rd party or your own). For each processed class, you would first run the parser on the source file for that given java class and harvest the internal comments, and then augment the (standard) html produced by the (standard) doclet to add the code comments.

A possible strategy that would help make the resultant javadocs sensible would be to include a given method's internal comments for the javadoc for that method. Just use a 'pre' closure and append the parsed comments of the method at the end of the generic javadoc html.