IDEA Doc: Javadoc plugin

I'm curious. Why do you think such auto-generated documentation is
better than no documentation at all?

Onno Scheffers wrote:

Hi there,

just wanted to let you guys know I released a beta version of my first-ever IntelliJ IDEA plugin.
I put it on sourceforge for now until I get to a 1.0 release (which I will then upload to the plugin repository).
It's a plugin for generating javadoc for getters, setters, overriding methods and default constructors and it is template-based.

You can find information on the plugin at http://ideadoc.sourceforge.net

There are still some rough edges I would like to fix and I'm hoping someone could help me out:

- I added the ideadoc action into IDEA's Generate-menu. I noticed that the Generate menu with my
new action shows up even when pressing ALT+Insert outside Java-files (in XML files for example)
How can I make that action visible only when the other java generate-actions are visible (like 'generate getter')?

- Since the OpenAPI doesn't give access to the fileTemplates yet, I used the trick described here:
http://www.intellij.net/tracker/idea/viewSCR?publicId=41794
So then I can read the templates. I have to replace the predefined variables myself then if I'm
not mistaken. I did that for $ and $ as well, but I used a fixed locale now.
Is there any way to get to the current Date- and Time-formatter IntelliJ uses?

- I tested the fileTemplate location-trick on MAC OS X (10.3.9) as well, but it doesn't work for
writing new fileTemplates and since I'm a complete Mac newbie I was hoping someone would be
able to provide me with a solution that works on the Mac.
It seems that on the Mac, IntelliJ IDEA is a .app file, which is some sort of archive.
So I cannot write new templates to it. What is the best way to read and write fileTemplates on the Mac?

Hello Keith,

Because it tells you that there's really nothing interesting about the method,
and doesn't leave empty spots in the documentation.

(When I write JavaDoc comments for the OpenAPI, I strive to document all
methods in the classes I'm covering, and quite often my docs are no smarter
than something such a tool could generate.)

KL> I'm curious. Why do you think such auto-generated documentation is
KL> better than no documentation at all?
KL>
KL> Onno Scheffers wrote:
KL>
>> Hi there,
>>
>> just wanted to let you guys know I released a beta version of my
>> first-ever IntelliJ IDEA plugin.
>>
>> I put it on sourceforge for now until I get to a 1.0 release (which I
>> will then upload to the plugin repository).
>>
>> It's a plugin for generating javadoc for getters, setters, overriding
>> methods and default constructors and it is template-based.
>>
>> You can find information on the plugin at
>> http://ideadoc.sourceforge.net
>>
>> There are still some rough edges I would like to fix and I'm hoping
>> someone could help me out:
>>
>> - I added the ideadoc action into IDEA's Generate-menu. I noticed
>> that the Generate menu with my
>>
>> new action shows up even when pressing ALT+Insert outside Java-files
>> (in XML files for example)
>>
>> How can I make that action visible only when the other java
>> generate-actions are visible (like 'generate getter')?
>>
>> - Since the OpenAPI doesn't give access to the fileTemplates yet, I
>> used the trick described here:
>> http://www.intellij.net/tracker/idea/viewSCR?publicId=41794
>> So then I can read the templates. I have to replace the predefined
>> variables myself then if I'm
>> not mistaken. I did that for $ and $ as well, but I used
>> a fixed locale now.
>> Is there any way to get to the current Date- and Time-formatter
>> IntelliJ uses?
>> - I tested the fileTemplate location-trick on MAC OS X (10.3.9) as
>> well, but it doesn't work for
>>
>> writing new fileTemplates and since I'm a complete Mac newbie I was
>> hoping someone would be
>>
>> able to provide me with a solution that works on the Mac.
>>
>> It seems that on the Mac, IntelliJ IDEA is a .app file, which is some
>> sort of archive.
>>
>> So I cannot write new templates to it. What is the best way to read
>> and write fileTemplates on the Mac?
>>
--
Dmitry Jemerov
Software Developer
JetBrains, Inc.
http://www.jetbrains.com
"Develop with pleasure!"

I'm curious. Why do you think such auto-generated
documentation is better than no documentation at all?

I'm not saying it is better. It's just that I've worked at several customers now that require every method to be documented. Even method like getters and setters.
Mostly just to make them pass Checkstyle validation.

Since the customers require it, I have no choice but to provide it.

I see a lot of copy-paste mistakes being made because of this, leading to javadoc that does pass Checkstyle validation, but does not make sense for the method it's supposed to document.

That's why I wrote this plugin. It makes things easier, less cumbersome and puts an end to the annoying copy-paste mistakes.

(When I write JavaDoc comments for the OpenAPI, I
strive to document all
methods in the classes I'm covering, and quite often
my docs are no smarter
than something such a tool could generate.)

Hi Dmitry,

good to see you feel the same way. Does this mean IntelliJ will get native support for javadoc templates in the near future?
I requested it a while ago and back then I was told it won't happen because it is considered bad practise to generate Javadoc.

Hello Onno,

>> (When I write JavaDoc comments for the OpenAPI, I
>> strive to document all
>> methods in the classes I'm covering, and quite often
>> my docs are no smarter
>> than something such a tool could generate.)
OS> Hi Dmitry,
OS>
OS> good to see you feel the same way. Does this mean IntelliJ will get
OS> native support for javadoc templates in the near future?

We haven't really discussed this in the team. Personally, I think that as
a core feature, we could allocate only a limited amout of resources to it,
while a separate plugin developer can dedicate much more time and effort.
The GhostDoc plugin for Visual Studio is a good example of this, and I'd
love to see something as powerful for IntelliJ.

OS> I requested it a while ago and back then I was told it won't happen
OS> because it is considered bad practise to generate Javadoc.

We consider bad practice mass generation of JavaDoc comments (for all methods
in the class, for example). When you do look at each individual method and
decide that a template comment would be appropriate (or a good starting point
for manual writing), I don't see anything bad in that.

--
Dmitry Jemerov
Software Developer
JetBrains, Inc.
http://www.jetbrains.com
"Develop with pleasure!"

That's a grat plugin!

especially for setters/getters where the name is already fine.
thank you very much!

-claude

Hi Onno,

Welcome to the world of plugin development :)

You should upload your plugin to the plugin manager even though
you're still in the early stages. It is much easier for people to use the
PM to download and try things out rather than having to go
somewhere else (especially sourceforge).

Do you have any plans to provide mechanisms to deal with existing
javadocs? I've often run into situations where we decide to add or
remove tags or javadoc elements to existing javadocs. For exemple,
we recently decided to remove all @author, @version and @since
tags on a 3,500+ file codebase. Having a tool that would allow us
to do these kinds of operations safely across the entire source tree
without modifying anything else would be very valuable.

Good luck with the plugin!

Vince.

The GhostDoc plugin for Visual Studio is a good
example of this, and I'd
love to see something as powerful for IntelliJ.

I never heard of it before, but looking at the introduction-movie they provide on their website it does indeed seem to be extremely powerful.

Welcome to the world of plugin development :)

Thanks :P

You should upload your plugin to the plugin manager
even though
you're still in the early stages. It is much easier
for people to use the
PM to download and try things out rather than having
to go
somewhere else (especially sourceforge).

I agree, but I just want to finish these last few issues before doing so. If the downloaders are anything like me, they will install the plugin and not check for updates on it once it gets the work done. And I especially want to make sure it works on all supported platforms (it doesn't work on the Mac yet).
So I thought I put it here so people could see it and give some early feedback and maybe help me out with the remaining issues first.

Do you have any plans to provide mechanisms to deal
with existing javadocs?

It sounds very useful, but I haven't thought that far ahead yet. Just created the plugin because I needed it.
The first new feature I want to add (probably for a 2.0 release) is to iterate over entire project/modules/dirs, since now you still have to execute the plugin per file yourself.

we recently decided to remove all @author, @version
and @since tags on a 3,500+ file codebase.

I would think an IDEA macro could facilitate that?
But still.. I agree it would be usefull to have a kind of template for the non-required javadoc (like the tags you mention) and once you adapt the template you could update all javadocs in one go (kinda like the copyright plugin does for copyright messages above the code).
It's just too bad that doing even the simplest thing in plugins takes ages of Google'ing around and searching the forums. I have plans for much bigger plugins (like a Tapestry plugin and integration with a new Web Framework I'm currently writing), but the lack of good plugin-documentation stops me from creating them.

Good luck with the plugin!

Again.. Thanks.

You're welcome.

Hello Onno,

OS> It's just too bad that doing even the simplest thing in plugins
OS> takes ages of Google'ing around and searching the forums. I have
OS> plans for much bigger plugins (like a Tapestry plugin and
OS> integration with a new Web Framework I'm currently writing), but the
OS> lack of good plugin-documentation stops me from creating them.

If you can tell us about specific areas where you have encountered difficulties
or incomplete documentation, please do, and we'll try to improve the documentation
for them.

Note that the API documentation in the 5.0.2 update has been significantly
expanded compared to the original 5.0 release.

--
Dmitry Jemerov
Software Developer
JetBrains, Inc.
http://www.jetbrains.com
"Develop with pleasure!"

If you can tell us about specific areas where you
have encountered difficulties
or incomplete documentation, please do, and we'll try
to improve the documentation
for them.

Note that the API documentation in the 5.0.2 update
has been significantly
expanded compared to the original 5.0 release.

Well.. answering the items I put forward in my initial post would be a start :oP

To be fair, I have worked from the OpenAPI I downloaded along with IntelliJ 5.00, so I'll first check if that 5.02 documentation is better, because the 5.00 API-docs were mostly just empty.

But in general it's just very hard to get into plugin development for IntelliJ. If you have no prior knowledge of the openAPI it's very hard to just find out how to get to the file you're currently editing and how to alter that file from an Action. I'm sure it gets much easier once you know your way around the API.
I spent about two days of work on this plugin, while the actual Java code could easily be written in an hour or so. Just finding out what to use to get to the parts I need takes a lot of searching. I've tried it before a couple of times and each time I got so demotivated I just gave up. It simply costs too much time to get the simplest of things done.
If you Google around for tutorials on how to write plugins for Eclipse you get a lot of hits. For IntelliJ we're mostly stuck with some very limited examples, some example code and other peoples work.

Maybe just an overview of all factories and services with a short description and an overview of names to use in the plugin.xml to add an action after an existing element in a menu for example.
And a list of String literals/Constant definitions used for locating the current Class or method.

I really miss just some basic tutorials or -better yet- a book on how to write plugins. It should be easy to find out how to do something (like going through a book's alphabetic index to find the subject you're interested in).
I did like the Custom Language API Tutorial I've seen posted on this forum somewhere. That's the kind of thing we need for much more subjects.

I read a while back some people were working on a book on plugin-development, but I couldn't make it if it was going to be available in English?

Anyway. I'll download the latest API-docs and will give feedback on it later this week (probably somewhere this weekend).

I also need some generated Javadocs because of customer requirements. Your plugin looks great! It may save me from some painful Eclipse time. But, my customer requires a different substitution for overriding methods: an @see to the overridden method (with full package name, because Eclipse doesn't understand imports for Javadocs). The Eclipse template looks like /** $ */.

Also, I tried your plugin on a getter in an abstract class Foo, but had a problem. It generated /** Do not instantiate Foo. */ (all on one line), altho my JavadocForGetter template defaulted to
/**

• Getter for property '$

  • @return Value for property '$
  '. * '.

*/

Should I look at something? I may not have time to get into this.

Cheers,
11011011

I also need some generated Javadocs because of
customer requirements. Your plugin looks great! It
may save me from some painful Eclipse time. But, my
customer requires a different substitution for
overriding methods: an @see to the overridden method
(with full package name, because Eclipse doesn't
understand imports for Javadocs). The Eclipse
template looks like /** $ */.

I had another feature request for @see in getters/setters (pointing to each other when they are available).
I've put both requests on my TODO-list for the next beta-release.

Also, I tried your plugin on a getter in an abstract
class Foo, but had a problem. It generated /** Do
not instantiate Foo. */ (all on one line), altho my
JavadocForGetter template defaulted to

I'm looking into that as well. I started seeing that problem myself after I upgraded to IntelliJ 5.02 (which may also mean I just wasn't paying attention to it before). Also on the TODO list for the next beta-release.

Should I look at something? I may not have time to
get into this.

Time's always a problem for me as well.
So it will probably be a couple of weeks before I am ready with the Beta 5 release (somewhere in januari I think).

I've already rewrote quite some code to add support for MacOS and to support inner-classes properly.