This discussion is archived
9 Replies Latest reply: Aug 19, 2010 5:28 AM by EJP RSS

Javadoc 7: Separation of static from instance members

843810 Newbie
Currently Being Moderated
For JDK 7, we are implementing an enhancement to the Javadoc tool to separate static members from instance members and add pull-down menus for members.

Here is our proposal:
[Separating Static from Instance Members|http://sites.google.com/a/dougkramer.org/doug-kramer/static-instance]

Comments welcome -- just add them to the bottom of that web page.

Doug Kramer
Josh Bloch
  • 1. Re: Javadoc 7: Separation of static from instance members
    EJP Guru
    Currently Being Moderated
    Very nice, gentlemen, I like it.

    Hi Doug.
  • 2. Re: Javadoc 7: Separation of static from instance members
    843810 Newbie
    Currently Being Moderated
    While I think this is (or rather would have been) a good idea I don't think I like it.

    What I mean is that on face it's a good idea, and helps makes thing clear (although the static modifier already made it pretty clear) but I don't care for splitting the methods into the two table chunks like that when it's never been that way before. I am too used to the other way. I just know I will spend time going "where the heck is getFoo and why is everything static" as I scroll alphabetically through method summaries forgetting that there is now a second chunk of method summaries.

    I like the menus.

    I guess if it was up to me I would keep the menus with the split and keep the full alphabetically sorted list of methods in the summaries like now.

    Or maybe I'll just get used to it...
  • 3. Re: Javadoc 7: Separation of static from instance members
    843810 Newbie
    Currently Being Moderated
    I've thought about that issue, where users could get lost in a very long page of methods. How about this idea...

    Floating side heading - NOTE: This prototype is a preliminary design and is not fully functioning. It displays a small, green box, aligned right, that contains the name of the class and section you're viewing, with a link to the top of the page, shown in this example as:
    String - Static Methods |  TOP
    The section heading "Static Methods" should change to "Instance Methods" when you scroll down into that detail section -- but the JavaScript has not yet been written to do that. The floating side heading would disappear when you are viewing the summary tables.

    [String class with a floating side heading|http://1.latest.javadoctool.appspot.com/api-float-heading/String.html#valueOf(char)]

    Would that help, or can you think of another way to expose the name of the section you're in?

    Does "TOP" clutter this box, or should it be implemented as right-aligned carets as shown here: [Jump-to-top links|http://1.latest.javadoctool.appspot.com/api-jump-to-top/java/lang/String.html#getBytes()]
  • 4. Re: Javadoc 7: Separation of static from instance members
    EJP Guru
    Currently Being Moderated
    Sorry to add a bit of scope creep here but I am thinking of users of the JDK Javadoc. You might want to think about making this kind of thing configurable at runtime, instead of specifiable at Javadoc-time, so that the user can choose dynamically between e.g. the 'classic' view and the new static-separated view. I know just enough about Javascript to know that it's possible ...and dangerous ...
  • 5. Re: Javadoc 7: Separation of static from instance members
    843810 Newbie
    Currently Being Moderated
    Making this configurable while viewing is indeed more desirable, and one that we considered, but would have made long pages more sluggish to load. After all, you would need to sort all members on the fly if you chose the non-default case (unless the HTML source included both sortings and displayed only one). We wanted to keep the pages feeling snappy. We could change this when sorting in browsers is faster.

    There are settings that could easily be made on the fly without this tradeoff, such as hiding protected or deprecated members.
  • 6. Re: Javadoc 7: Separation of static from instance members
    843810 Newbie
    Currently Being Moderated
    I've finally implemented the floating side heading (on the single class String):
    [String class with floating side header|http://1.latest.javadoctool.appspot.com/api-float-heading2/String.html#valueOf(char)]

    The floating header looks like this, in the upper right corner
    String > Static Methods
    The section heading "Static Methods" changes to "Instance Methods" when you scroll down into that detail section.

    The link on the class name jumps to the top of the page. This is a convenience to get back to the menus at the top.

    As always, comments are welcome.
  • 7. Re: Javadoc 7: Separation of static from instance members
    EJP Guru
    Currently Being Moderated
    Very nice Doug. I guess it's too much to ask for the RHS of the floating display to become a drop-down menu?

    EJP
  • 8. Re: Javadoc 7: Separation of static from instance members
    843810 Newbie
    Currently Being Moderated
    Thanks. Yeah, a link to the top of the "Static Methods" detail section, say, doesn't seem very useful (but is consistent with the "String" link).

    What would you want in the menu?

    The obvious choice would be for the "Static Methods" drop-down menu to list the name of the static methods. (But it's a bit odd that the current drop-down list is in alphabetic order, while the method descriptions are in source order. Changing the order of the latter is out of scope for this work.)

    But maybe it would be more useful to list the sections, to let you jump to them, such as:
    Static Fields
    Constructors
    Static Methods
    Instance Methods
    In any case, I need to submit the patch in the next few days, and probably would have to do this work as a separate patch, assuming I could find the time.
  • 9. Re: Javadoc 7: Separation of static from instance members
    EJP Guru
    Currently Being Moderated
    I was thinking the obvious choice would be just be the section headings: fields, ctors, statics, non-statics. At least that way it would all be fixed, not generated per page, so actually the Javascript and the anchors would all be fixed.