[ANN] JavaDocEditorPlugin 1.1

The changes for 1.1 are:

- added text wrapping (thanks to Erwin Tratar)
- ]]> tags are not formatted

The total list of features:

  • Shows and edits javadoc for classes, fields and methods in gui

  • Automatically picks up parameters, return and exception info and merges it with existing javadoc if there is a conflict or

mismatch

  • Converts regular and line comments into javadoc

  • Does not format text between <pre></pre> tags

  • Formats javadocs using the following settings:

  • (do not) align parameter comments to longest parameter name (min and max)

  • (do not) align exception comments to longest exception name (min and max)

  • (do not) add blank line after all @param tags

  • (do not) add blank line after @return

  • (do not) add blank line after all @throws tags

  • (do not) add blank line after description

  • (do not) add blank line after the whole javadoc

  • keep/remove non-standard tags

  • keep/remove empty lines

  • (do not) add <p/> at empty lines

  • generate @throws, not @exception

  • (do not) generate @param with empty description

  • (do not) generate @return with empty description

  • (do not) generate @throws with empty description

  • wraps text at specified column


http://www.intellij.org/twiki/bin/view/Main/JavaDocEditorPlugin

--
Dmitry Skavish
-


Boston, MA, USA
tel. +1 781 370-6909
http://www.jzox.com
http://www.flashgap.com

9 comments
Comment actions Permalink

Great plugin idea!
Here are a two ideas/suggestions:
- HTML editing
- Propose to automatically fill the @see tags list with all methods that
call the current method.

Dmitry Skavish wrote:

The changes for 1.1 are:

- added text wrapping (thanks to Erwin Tratar)
- <pre> tags are not formatted

The total list of features:

  • Shows and edits javadoc for classes, fields and methods in gui

  • Automatically picks up parameters, return and exception info and

merges it with existing javadoc if there is a conflict or mismatch

  • Converts regular and line comments into javadoc

  • Does not format text between <pre></pre> tags

  • Formats javadocs using the following settings:

  • (do not) align parameter comments to longest parameter name (min

and max)

  • (do not) align exception comments to longest exception name (min

and max)

  • (do not) add blank line after all @param tags

  • (do not) add blank line after @return

  • (do not) add blank line after all @throws tags

  • (do not) add blank line after description

  • (do not) add blank line after the whole javadoc

  • keep/remove non-standard tags

  • keep/remove empty lines

  • (do not) add <p/> at empty lines

  • generate @throws, not @exception

  • (do not) generate @param with empty description

  • (do not) generate @return with empty description

  • (do not) generate @throws with empty description

  • wraps text at specified column


http://www.intellij.org/twiki/bin/view/Main/JavaDocEditorPlugin


0
Comment actions Permalink

I just noted that when I simply open the javadoc editor and press OK,
the "]]>" tags disappear.

Dmitry Skavish wrote:

The changes for 1.1 are:

- added text wrapping (thanks to Erwin Tratar)
- <pre> tags are not formatted

The total list of features:

  • Shows and edits javadoc for classes, fields and methods in gui

  • Automatically picks up parameters, return and exception info and

merges it with existing javadoc if there is a conflict or mismatch

  • Converts regular and line comments into javadoc

  • Does not format text between <pre></pre> tags

  • Formats javadocs using the following settings:

  • (do not) align parameter comments to longest parameter name (min

and max)

  • (do not) align exception comments to longest exception name (min

and max)

  • (do not) add blank line after all @param tags

  • (do not) add blank line after @return

  • (do not) add blank line after all @throws tags

  • (do not) add blank line after description

  • (do not) add blank line after the whole javadoc

  • keep/remove non-standard tags

  • keep/remove empty lines

  • (do not) add <p/> at empty lines

  • generate @throws, not @exception

  • (do not) generate @param with empty description

  • (do not) generate @return with empty description

  • (do not) generate @throws with empty description

  • wraps text at specified column


http://www.intellij.org/twiki/bin/view/Main/JavaDocEditorPlugin


0
Comment actions Permalink

Guillaume wrote:

I just noted that when I simply open the javadoc editor and press OK,
the "<p>" tags disappear.


I guess it's a bug, but you can try to enable two options to insert ]]> tags at empty
lines and to keep empty lines, it should fix it.

--
Dmitry Skavish
-


Boston, MA, USA
tel. +1 781 370-6909
http://www.jzox.com
http://www.flashgap.com

0
Comment actions Permalink

Great plugin idea!
Here are a two ideas/suggestions:
- HTML editing



This is while definitely useful, but requires some time to implement which I am
not sure I have.

- Propose to automatically fill the @see tags list with all methods that
call the current method.


This is a good idea and I think I can do it as an option.

Another thing I am going to add (I am working on that right now) is to be able
to edit all these xdoclet tags. The descriptions for some particular xdoclet can
be specified via xml files, so adding some new namespace is just a matter of
creating a corresponding xml file. The gui will pick it up automatically.

I think I will release new version with this functionality next week.

--
Dmitry Skavish
-


Boston, MA, USA
tel. +1 781 370-6909
http://www.jzox.com
http://www.flashgap.com

0
Comment actions Permalink



>> - Propose to automatically fill the @see tags list with all methods
>> that call the current method.


This is a good idea and I think I can do it as an option.


Perhaps it would also make sense to include the methods that are called by
the current method and methods in interfaces or superclasses that this
method overrides.

I know that I've done a significant amount of message forwarding and
delegation, and I usually like to document the fact that I'm just passing
the message on. In fact, I think I add @see for this more than I do for
methods that call the method being documented.

As for @see-ing the superclass or interface, I often do this with where I
need to provide an explicit, "This implementation..." in addition to the
inherited documentation.


~Mike

0
Comment actions Permalink

>>- Propose to automatically fill the @see tags list with all methods
>>that call the current method.
>
>This is a good idea and I think I can do it as an option.

>

Perhaps it would also make sense to include the methods that are called by
the current method and methods in interfaces or superclasses that this
method overrides.



Actually this is what I think he meant to :) At least that's how I understood it.
I don't see any rationale to put methods which call the current method into @see
tags of the current method. The other way around has perfect sense for me.
Or am I missing something?

I know that I've done a significant amount of message forwarding and
delegation, and I usually like to document the fact that I'm just passing
the message on. In fact, I think I add @see for this more than I do for
methods that call the method being documented.

>

As for @see-ing the superclass or interface, I often do this with where I
need to provide an explicit, "This implementation..." in addition to the
inherited documentation.


Yes, that's what I am planning to do.

--
Dmitry Skavish
-


Boston, MA, USA
tel. +1 781 370-6909
http://www.jzox.com
http://www.flashgap.com

0
Comment actions Permalink

Actually this is what I think he meant to :) At least that's how I
understood it. I don't see any rationale to put methods which call the
current method into @see tags of the current method. The other way
around has perfect sense for me. Or am I missing something?


I can see the other version in the case of methods within the same class
(or superclasses). Otherwise, I think you're right.

>> I know that I've done a significant amount of message forwarding and
>> delegation, and I usually like to document the fact that I'm just
>> passing the message on. In fact, I think I add @see for this more
>> than I do for methods that call the method being documented.
>>
>> As for @see-ing the superclass or interface, I often do this with
>> where I need to provide an explicit, "This implementation..." in
>> addition to the inherited documentation.


Yes, that's what I am planning to do.


Great, thanks.

This is a great overall plugin concept; IMHO it is one of the best uses
of the OpenAPI so far.


~Mike

0
Comment actions Permalink

This is a great overall plugin concept; IMHO it is one of the best uses
of the OpenAPI so far.



Thanks, although I don't see anything special here :)


Damn, I told myself several times to never write anything which I am not familiar with
or at least to do some research first. So I don't actually use xdoclet and don't know
much about it, but since I wrote this plugin (javadoc editor) I figured I can add some
kind of xdoclet gui editor to it pretty easy. Well, after several days working on that
(with short breaks to attend stupid meetings on my job) I found that there is already
excellent gui/tool for that and even plugin for idea (xdocletgui module on xdoclet.sourceforge.net)!
Damn, so much time wasted! I hope that at least I learned something from it :)


--
Dmitry Skavish
-


Boston, MA, USA
tel. +1 781 910-3810
http://www.jzox.com
http://www.flashgap.com

0
Comment actions Permalink

Thanks, although I don't see anything special here :)


My comment is based upon the fact that this plugin accomplishes a bit
more than most. For example, my own plugin doesn't do much other than
expose something that is already provided by IDEA. Yours is considerably
more involved:
- it parses the PSI for fields and methods and their parameters,
return types, etc
- it reformats the comments properly
- it has its own GUI for editing JavaDoc.

Note, I'm not saying it's THE best. I haven't decided which one that is.
;)

However, SimpleUML and the SelectorPlugin are probably the frontrunners
(IMHO, of course).

~Mike

0

Please sign in to leave a comment.