Amy Fowler's Blog

Invitation to weigh in on the future of javadoc

For some time I've been peddling this theory that one of the greatest barriers to Swing adoption is our monolithic API documentation (javadoc). I'm a personal fan of javadoc and rely on it for solving a large percentage of my programming questions, but you could say I know where to look, and that, at least in the Swing case, over the years my brain has learned to block out that 80% which isn't actually needed to construct a GUI. Picking on JButton - I only really need 3 or 4 of the 300+ methods and the ones I need arn't even listed in the Method Summary table because they are actually defined in its superclass, AbstractButton. But I know that, so it's not a problem. But what about the poor soul embarking on his or her first Swing client? And of course this problem isn't limited to Swing, but afflicts many of the larger APIs in J2SE (JDBC, XML, etc). Sometimes bigness creeps up on you.

Javadoc's structure really hasn't changed at all in the last 10 years because it serves quite well as the Java platform's API reference. The questions we are trying to answer for JSR260 are should it evolve? and how? So I entreat you to take this short(!) survey and tell us what you think:

http://java.sun.com/webapps/survey/display?survey_id=5382

Your answers will make a difference.

Comments

• The survey is flawed. Where it says "check all that apply", I have to at least check one, or otherwise the system says my entry is incomplete.

  So I had to check one even though none applies to me.

  Posted by: kohsuke on January 27, 2006 at 08:46 PM

• How would you like to see the J2SE generated API documentation improved?
  Be easier to search.
  Another interesting idea would be to make the official APIs in Sun's site a sort of WIKI. Not a wiki where you can modify all you want (obviously because the APi cannot be changed!) but a page where you can add 2 kind of information:
  1) the possibility to link a class with related tutorials. The tutorials could be Sun's own tutorial in java.sun.com or may be even reputable tutorials outside Sun (but there you would have to watch out for abuse).
  2) the possibility to add some comment to a method or class. May be a model would be the documentation of MySQL. You can read/download the documentation with or without user comments.

  Posted by: imjames on January 27, 2006 at 11:30 PM

• 
  Given certain annotations? javadoc comments? that "tag" an API element, provide a simple browsing interface that lets me see all API elements of a given tag.
  Trace call graphs to the extent possible (either automatically or as indicated by author's intent). What I mean is, if method B exists only because method A calls it, and if a subclass overrides method A, then method B is totally irrelevant with respect to that subclass. I should be able to have the tool figure this out for me and weed it out of the documentation in some way.
  Allow certain API elements to be notated as something like "entry points". Coupled with some degree of call graph identification, your tool can then begin to answer questions of the form, "OK, I have this API in front of me, where the bloody hell do I start?"
  Wild idea: consider tying javadoc to java.net in some weird way shape or form so that documentation can be filled in by the community, but in a slightly more legislated way than the wild west hullabaloo that is jdocs.org.
  Tie some of the Creator 2 UML stuff, now available for free as I understand it, so that rudimentary class diagrams can be generated or included as part of the javadoc output.
  Continue, please, to make it look and behave as little as possible like MSDN. What a horrible travesty and sin against mankind that is.

  Feel free to contact me at ljnelson@gmail.com.

  Posted by: ljnelson on January 28, 2006 at 05:21 PM

• How about this: add "categories" to Javadoc and then allow selective showing and hiding of documented items. For example, all PLAF related items, all visual properties, all behavioural properties. These could be added as annotations, for example:

  
  @javadocCategory({"visual"})
  public void setIcon(Icon icon) { ... }

  @javadocCategory({"plaf"})
  public LabelUI getUI() { ... }

  
  I'd suggest that this would allow you to:

  (a) Build javadocs that only had those items in which you are interested. For example an enterprise developer using Matisse to design UIs would probably not need to see docs for "visual" or "PLAF" items.

  (b) The on-line docs could hide or show items based on a user's preferences.

  (c) Use some smart CSS behaviours to show and hide categories.

  Building a set of documentation that only shows public, non-deprecated items in the relevant categories could cut down on the volume quite a bit.

  Finally, they could be used to improve the quality of results of any search factility that is included in future.

  Posted by: iphillips on January 30, 2006 at 06:06 AM

• What about pushing for GroupLayout for Java 6 ?

  .V

  Posted by: netsql on January 30, 2006 at 06:37 AM

• 
  Hi.

  I did fill out the survey too; and it might be good to see nice improvements; but I'd also just like to add that it would hurt a lot if they lost any of the utility they currently do have -- the no-frills view of 'exactly what is here' is very important, which you get with the class detail page, like "javax/swing/JList.html", which just shows you the parts of the API without trying to preach to the choir.

  And if it became harder to write the docs for the developer, then that would also be a killer. But I'm not trying to depress you!... The best improvement might be to figure out how to get us to stop pressing command-spacebar and go back more into reading the actual documentation in the presentation format the author envisioned us reading it in! There is a lot of useability lost in that translation; but I guess most likely you're supposed to tell me to "just stop doing that if it hurts".

  Ow!

  OK. Bye.
  

  Posted by: steevcoco on January 30, 2006 at 07:51 AM

• JavaDoc can help separate the API needed to use a class from the documentation needed to extend it (perhaps using categories as suggested previously). Some of that can be done today by only generating JavaDoc for public members, but the poor granularity of package access will force the inclusion of many unnecessary members (remember Component.getPeer()?). NetBeans has made improvements the past few years in its architecture by requiring the separation of API from SPI, or application versus service-provider use. The Java core classes can't be rearchitected, but the documentation can be tagged in a similar way without affecting compatibility.

  Posted by: tball on January 30, 2006 at 08:55 AM

• I have a small project where I try to teach someone Java. The guy knows close to nothing to programming in virtual machines, has a slight understanding of OO, etc. A beginner.

  One of the things he came to me with was the Looks of Javadoc. He said that looking at Javadocs just makes him tired as there aren't many colours, backgrounds to differenciate between methods and explanations and examples.

  I bet that using a few additional tags and a good style sheet will solve this problem - Is this what you're looking for?

  (Haven't done the survey yet, it's a bit of a problem at this current computer, will do it tomorrow morning :))

  Posted by: aviadbd on January 30, 2006 at 10:42 AM

• What i would like to see :
  - dynamic grouping/sorting and hiding. With DHTML now supported by most (if not all) browsers, it could be done easily. Of cource a plain old version without dynamic scripts or frames should be also available, as it is now.
  - standard "native" help format bundled in JDK installation where available (WinHelp on Windows, DocBook on linux, ...)
  - a search tool (an applet?) for html version on other plateforms and online help
  - clearly state in javadoc for methods that overides a super class method or that implements an interface method, and link to that super method ("see also" should be reserved for other related functions). A tag is not necessary as this could be automatically inferred
  - categorize methods by field of use (e.g. events, plaf, dimension, visual behavior, ...), usage (common use, implementation specific/internal "public" method) and specific function (getter/setters, factory methods, ...). I think field of use and common use markers should be javadoc tags, whereas internal plublic methods, getters/setters and factory markers should be java5 annotations.
  

  Posted by: efayol on January 30, 2006 at 12:18 PM

• I think Swing hasn't been adopted to a greater extent is because

  Most Java developers are more interested in web development
  Past Swing/Java performance problems are still viewed as existing problems
  Past fat client deployment problems are still viewed as existing problems
  Swing is only a component library and does not readily help developers create applications
  Java/Swing uses a lot of memory
  The JRE is huge making deploying it w/ your app daunting

  Posted by: neilweber on January 30, 2006 at 02:32 PM

• In reply to imjames:

  I like your suggestion, being able to add user comments to the api would be great. I also devellop in PHP, and find the comments with the documentation very helpfull. There should be some editorial proces to filter the amount of comments though.

  Posted by: ttsgosadow on February 01, 2006 at 06:28 AM

• There are two separate issues:
  - Content (what should be included in documentation)
  - Presentation (how it should be presented)

  Having said this, it would make sense to produce documentation not in the HTML format, but rather in the XML format and provide a standard stylesheet (or a few stylesheets) that would allow not only to produce different L&F of JavaDoc, but also possibly to different audiences (programmers vs architects vs business analysts, etc).

  This would let to achieve a few goals.
  - The discussion as to how it javadoc should look becomes a completely separate issue
  - It would be easier for IDEs to process XML documentation for context sensitive help

  As a few notes aside.
  - It would be great to be able to merge JavaDoc. Now I have one window for J2SE, another for J2EE, another for .... And if, for example, J2EE javadoc is plugged in, it would recognize the presense of J2SE documenation and resolve links to its classes.
  - As noted, initial documentation format is about 10 years old and was targeted at first browser. Now browsers provide richer UI.

  Javadoc for big packages is big and it becomes extremely hard to browse:
  - package list is long (a package tree would solve this problem)
  - class list is long (an incremental search should help here)
  - if a class is big it also pretty hard to read/browse. Wouldn't it be nice to provide subnodes for methods, fields, internal classes, etc.?
  If you are looking to improve javadoc, go to GJT (http://gjt.org/javadoc/index.html) and search, for example, how I can do wild card comparison. There are a few other suggestions as to what can be done with JavaDoc. Feel free to contact me linkedin [at] solarapex [dot] com.

  Posted by: solarapex on February 07, 2006 at 11:46 AM

• A top feature for me would be keyword and permuted indices, if not a Google-style search.

  Another would be support for the near ubiquitous @todo marker.

  And while there, adding tags for invariants would also help ala Design by Contract style programaming: @pre, @post and @invariant.

  Yet another would be links or references to test classes giving unit testing a more official status than it presently has. Just to present a concrete proposal, a @test tag--similar to the @see tag--to mark test classes and methods related to the current class or method would be helpful.

  Posted by: binkley on February 12, 2006 at 05:33 AM

• I wrote a JavaScript search function that works with ALL javadocs and makes them 10x easier to use. Please, please, please add it to the next version of JavaDoc.

  It's a case-insensitive search box that searches the 'all-classes' window pane. It opens the javadoc if it's found and scrolls the 'all-classes' pane to the approximate position... so even if it's not found you can see the surrounding classes. It's sometimes useful to just type 'R' to see all the classes that start with 'R,' for example.

  I put up an example for you to see Here. Thankyou.
  

  Posted by: davidbrady on February 12, 2006 at 01:49 PM

• I get a NOT FOUND error on submission. Argh. Here are my comments:

  The javadoc-generated API docs are one of the greatest strengths of Java. Some suggestions:
  1. Display the value of all constants in the main docs for that constant, rather than having to jump to a link.

  2. Cross-reference all Sun-created javadocs. That is, JEE docs should link to J2SE docs, etc. This can be done today.

  3. Add some sort of annotation to types (classes and interfaces) to show what API they are part of, such as part of JEE, part of J2SE, and so on. JEE, for example, has some JDBC classes that extend the regular API. Sometimes it is hard to tell what's where and which jars you need for an app.

  4. Get rid of parameterized types, which make javadoc uglier than sin. Tell the C++ folks to go back to C++. :-)

  Javadoc is really, really great.
  -Eric
  

  Posted by: ericfj on February 13, 2006 at 06:52 AM

• Some more suggestions:

  Really, really change the documentation of parametrized types. Whoever at Sun had the great idea to copy the practice from C++ to use single uppercase letters for type parameters, get that person fired! Instead of using junk like 'E' or 'T' use words like 'ElementType'.
  Threading behavior is often not documented at all or just hidden in some text. Get some formal tags so one can specify if a method / class is thread safe and to what extend.
  The API documentation is not only Sun's reference documentation, but also the sole specification for most of the APIs. However, for a specification the information is often imprecise (e.g. the mentioned threading behavior).
  Do not go to XML. Currently javadoc can still be written with a normal editor. When the XML fanboys get their saying, one would need yet another special editor and fight with even more nested elements than just the current HTML stuff.
  Improve the visualisation of class relations. The "Uses" links are a step in the right direction, but class diagrams like the ones produced by Doxygen would be an enhancement.
  

  Posted by: ewin on February 13, 2006 at 03:03 PM

• > Do not go to XML. Currently javadoc can still be written with a normal editor.

  I didn't get what you meant be 'normal/special editors', but I guess you meant javadoc comments, not generated documentation. I would like to clarify my point. I didn't mean to force using XML in java doc comments. What I meant is that javadoc tool would generate documentation in XML (may be in the Docbook (docbook.org) format or something customized for Java), not in HTML as it is now. The javadoc tool would still be able to produce old-style HTML documentation from the generated XML documentation after applying a standard stylesheet. Really, benefits of being able to get Java documentation in XML are greater than they seem to be.

  Posted by: solarapex on February 13, 2006 at 03:43 PM

• 
  There ought to be a mechanism to "flatten" the JavaDoc based on some tagging. One ought to still be able to view the hierarchical version but a developer or tech writer ought to be able to make a swag at what will be commonly used methods.

  The JButton, for example, inherits for AbstractButton where the addActionListener resides. It ought to be possible to get a flattened view where that method is shown as part of a bottom level API. Not as a member as "declared" in JButton, but as part of the standard methods used with a JButton. That would include elements all the way up the inheritance. For example, the setVisible method on the Component.

  Will everyone agree what the flattened set of methods are? Of course not, let's all piss and moan about it and the right ones will bubble up or trickle down. But, I can't recall the last time, if every, I used the getUIClassId() method but there it is right at the bottom level.

  Basically, I think the question should be like this: if we were designing a UI layout tool, which properties would we want to expose to the user for setting at layout time? The methods that access those properties would nearly always be in the flattened view.

  Posted by: bradleej on June 30, 2006 at 08:58 AM

This work is licensed under a Creative Commons License.