This content has been marked as final. Show 9 replies
Very nice, gentlemen, I like it.
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...
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
[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()]
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.
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
The section heading "Static Methods" changes to "Instance Methods" when you scroll down into that detail section.
String > Static Methods
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.
Very nice Doug. I guess it's too much to ask for the RHS of the floating display to become a drop-down menu?
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:
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.
Static Fields Constructors Static Methods Instance Methods