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?
3 comments

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!

0

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!

0

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.

0

Please sign in to leave a comment.