Javadoc editor/formatter wish list

I am a programmer, but I always want my code to be well documented.  I have found the support for javadoc in IntelliJ to be OK, but missing a lot of support.

I have decided that I should try to do something about it instead of merely filing requests and bugs.

So I'm starting to work on a Javadoc plugin, and am wanting help, both in design and implementation.  The plugin API is formidable, so having someone to help me orient myself would be nice.  But I also want to know other people are interested in.

Here is my starting list:

(*) Apply HTML formatting to javadoc comments, so that it can handle <ul>, <ol>, and so on.

(*) Have a live window showing the generated document, which updates as I modify the javadoc.

(*) Have the generated form of the javadoc be what's shown in the source view, along with an "Edit" button that lets me edit the underlying javadoc source.

(*) Get the find system treat doc comments description as a single line of text, and leading '*' in doc comment as a space, so "x *y" will find x followed by a y, even if it is in
     * x
     * y

(*) Enforce some style rules, such as letting you say that only <tt> should be use for code font, changing <kdb> and <code> to <tt> (or whichever way you like).

(*) Recognize that many things get repeated in different doc comments.  For example, there may be a parameter named "color" in many methods in a class, and it is likely that the same description should apply to all of them in the @param documentation.  I want to be able to use a form of completion to let me pick descriptions from other doc comments, and then remember the connection, updating the text of all the @param tags that were sharing text if I edit one of them.

The last is the bulk of the work (and benefit, I think).  All sorts of boilerplate text goes in to javadoc, and once it's written, it takes a lot of work to change.

That's what I've got for ideas.  What else might help out the task of javadoc writing?
Comment actions Permalink

To answer your question about "what might help out the task of javadoc writing", I would recommend a book, Clean Code, by Robert C. Martin. Please read the chapter on comments and documentation. I know it's a complete different answer than you probably expected, but it has helped me a lot in writing (less!) documentation!

Comment actions Permalink

I write a lot of libraries, and for them, the clarity of the code does not help the person using it much.  They need API-level documentation, and shouldn't be looking at the code, if the doc makes that possible.

Still, I'm always happy to encourage clear, clean, simple code!

Comment actions Permalink

Ken are you still working on this? I've been hunting for a way to get IntelliJ to format Javadoc like Eclipse does (which is to include the HTML sub-formatting rules) for the last 6 months; I've looked at both Jalopy and JIndent, neither of which offer this.

So +1 from me with interest in what you are doing.


Please sign in to leave a comment.