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.