Annotations for documentation

This is just an idea I came up with during a discussion over at TheServerSide that I thought I'd share. The discussion was on the use of annotations as configuration, which made me realize that no one was really talking about the use of annotations as simple metadata.

Imagine you could specify a set of documentation annotations for a class or package, which have URLs as arguments. For example, I might specify something like


So far so good, you might say, but why not have all that stuff just hanging around in header comments, like we've always done. There are two important advantages that annotations have over comments. First, these annotations can be made to apply to compiled classes, not just source. That means that if you check a jar file out from a repository, it can include embedded documentation links. Second, annotations are easy to tool for. One can imagine right-clicking on a class or library in IDEA, and having a "Documentation" sub-menu sitting right under "Analysis" and "Refactoring". That sub-menu would be populated by introspecting the class or package for documentation annotations. Selecting one of the available documents would pop it up in your browser. Internally, this would be much like the current "External Javadoc" command, but auto-configuring and with arbitrary sorts of documentation available. Additional tooling around this (batch annotation tools, broken link checkers, missing annotation inspections) is obviously also possible.

Way more of my time than I would like is spent hunting down documentation for projects I'm dependent on. Hell, too much time is spent on hunting down documents for the project I'm actually working on. The creation of Google provided easily the second biggest improvement in my workflow in the last decade, after the creation of IDEA. Given all that, while it may not seem like it on the surface, but I believe support for documentation annotation would be a big win in the "Develop with pleasure" department.

Now none of this is particularly difficult, or indeed technologically all that interesting. An experienced plugin author could probably churn out an incredibly kick-ass demo for this in a long afternoon. I won't even plead lack of time as the reason I don't just do it myself. The problem is that this all has network-effect implications, in as much as the big benefit of it comes when library vendors start including doc annotations in their offerings. Sadly, that means the big win from this will only happen after including it in a major product, JSR work, working with people who know more library science that I do to come up with a sufficiently rich spec, and probably more hassles that I haven't even thought of. So I'm dumping it on the community, and see if enough people like the idea that JetBrains will bite.

Comments encouraged.

--Dave Griffith

8 comments
Comment actions Permalink

Oh, and the obvious place to experiment with documentation annotations is openapi.jar.

--Dave Griffith

0
Comment actions Permalink

Dave Griffith wrote:

 
> @Homepage("http://mycompany.com/myproject") 
> @Javadoc("http://mycompany.com/myproject/javadoc/MyClass.html") 
> @SpecificationDocument("http://mycompany.com/myproject/internal/spec.uml") 
> @License("http://mycompany.com/myproject/license.txt") public class MyClass{
>  //actual code. } ]]>


So far so good, you might say,


No, I don't say that. I think Javadoc combined with custom taglets are the right
way to do this. Javadoc is made for documentation. It still bothers me that
Nullable has a documentation attribute.

but why not have all that stuff just hanging
around in header comments, like we've always done. There are two important
advantages that annotations have over comments. First, these annotations can
be made to apply to compiled classes, not just source. That means that if
you check a jar file out from a repository, it can include embedded
documentation links.


I think this is not a common case. I don't use any code except idea.jar which
has no source.

Way more of my time than I would like is spent hunting down documentation for
projects I'm dependent on. Hell, too much time is spent on hunting down
documents for the project I'm actually working on. The creation of Google
provided easily the second biggest improvement in my workflow in the last
decade, after the creation of IDEA. Given all that, while it may not seem
like it on the surface, but I believe support for documentation annotation
would be a big win in the "Develop with pleasure" department.


I don't think it would help much, but it would be nice, and I think it should be
based on Javadoc tags and not on annotations.

0
Comment actions Permalink

+I think Javadoc combined with custom taglets are the right way to do this. Javadoc is made for documentation. +
...
+
I think this is not a common case. I don't use any code except idea.jar which has no source.+

On starting a new project, after downloading the source and libs from the repository, you need to find out parameter information about a method used from one of the libraries. Your way, the answer is

1)Google for the source, or external javadoc files.
2 a)If source is available, download and extract it, adding it as a sourcepath to the appropriate library, then generate the javadoc. It's a hassle, but probably worth it in the long run.
2 b)If source is not available but external javadoc is available, configure the URL in the settings panel. Alternatively, download the javadoc and put it on your local drive, and then configure the location in the setting panel.
3)Open up the javadoc, and get your information.

That's the best case, where the information you're looking for (e.g. a method parameter) is actually likely to be in the javadoc, rather than in one of the many other forms of documentation which infest coding projects like tapeworms.

I submit you are in a very unusual situation if all of your dependencies have available source. There's too many proprietary APIs out there, and probably more proprietary providers of open APIs. Consider clicking on a JDBC driver jar and being pointed to all the configuration doc available for it.

I do this sort of thing every day. There's gotta be a better way. While I agree that actual documentation content probably shouldn't be in annotations, I'm not sure what the objection to documentation references in annotations could be.

--Dave Griffith

0
Comment actions Permalink

This is just an idea I came up..........
Comments encouraged.

Before getting too excited, about annotations, read this :) :
http://www.theserverside.com/news/thread.tss?thread_id=36110

Ahmed.

0
Comment actions Permalink

Right, that was the thread I was referring to, about annotations for configuration. Other uses of annotations (including documentation) seem to be a lot less objectionable to those on the thread, and I was suggesting that support for documentation annotation would be a benefit to IDEA users.

--Dave Griffith

0
Comment actions Permalink

Cool, I like it. This would also greatly reduce the amount of
boilerplate comments in my code and instead I could just link to a
central location. This would make changes way easier.

Bas

0
Comment actions Permalink

I would love this, too. I've seen enough people just lazy enough
to never configure their libraries and either always wonder about
what the parameters to a certain method were, or repeatedly waiste
3 google-minutes finding it online, everytime.

Now for this particular purpose I wonder if annotating classes is the
right way to go. A lot of this information goes beyond the class
(in your example: license, homepage, possibly specs) and if each and
every class is annotated with the same information it could quickly
become a pain to maintain. OTOH attaching metadata for a whole
library could achieve most of this plug-and-play concept and could
be done directly at the JAR level (i.e. through Manifest). Maybe with
a good convention :)

Vince.


0
Comment actions Permalink

+1,
a package-level annotation with hints to where human or IDE could find
documentation for this package would be really nice.
Though I don't think it would be useful for a distinct class, probably since
javadoc is generated per-package

"Dave Griffith" <dave.griffith@cnn.com> wrote in message
news:15469413.1124904485780.JavaMail.itn@is.intellij.net...
This is just an idea I came up with during a discussion over at
TheServerSide that I thought I'd share. The discussion was on the use of
annotations as configuration, which made me realize that no one was really
talking about the use of annotations as simple metadata.

Imagine you could specify a set of documentation annotations for a class or
package, which have URLs as arguments. For example, I might specify
something like


So far so good, you might say, but why not have all that stuff just hanging
around in header comments, like we've always done. There are two important
advantages that annotations have over comments. First, these annotations
can be made to apply to compiled classes, not just source. That means that
if you check a jar file out from a repository, it can include embedded
documentation links. Second, annotations are easy to tool for. One can
imagine right-clicking on a class or library in IDEA, and having a
"Documentation" sub-menu sitting right under "Analysis" and "Refactoring".
That sub-menu would be populated by introspecting the class or package for
documentation annotations. Selecting one of the available documents would
pop it up in your browser. Internally, this would be much like the current
"External Javadoc" command, but auto-configuring and with arbitrary sorts of
documentation available. Additional tooling around this (batch annotation
tools, broken link checkers, missing annotation inspections) is obviously
also possible.

Way more of my time than I would like is spent hunting down documentation
for projects I'm dependent on. Hell, too much time is spent on hunting down
documents for the project I'm actually working on. The creation of Google
provided easily the second biggest improvement in my workflow in the last
decade, after the creation of IDEA. Given all that, while it may not seem
like it on the surface, but I believe support for documentation annotation
would be a big win in the "Develop with pleasure" department.

Now none of this is particularly difficult, or indeed technologically all
that interesting. An experienced plugin author could probably churn out an
incredibly kick-ass demo for this in a long afternoon. I won't even plead
lack of time as the reason I don't just do it myself. The problem is that
this all has network-effect implications, in as much as the big benefit of
it comes when library vendors start including doc annotations in their
offerings. Sadly, that means the big win from this will only happen after
including it in a major product, JSR work, working with people who know more
library science that I do to come up with a sufficiently rich spec, and
probably more hassles that I haven't even thought of. So I'm dumping it on
the community, and see if enough people like the idea that JetBrains will
bite.

Comments encouraged.

--Dave Griffith


0

Please sign in to leave a comment.