Free Deluxe Doclet - alternative Javadoc design

[eribe]

For a more luxurious Java API experience.
http://www.ida.liu.se/~eribe/deluxe

Primarily the Deluxe Doclet gives you faster API, with an organization
designed for programming and for successfully pairing very good
overview with quick and easy access to detail. Based on in-depth
research of API design. Try it out!

--
Erik Berglund (Ph.D.), www.ida.liu.se/~eribe
Adjunct Associate Professor
(Senior Lecturer)

Dept. Computer and Information Science.
Linköping University
S-581 83 Linköping, Sweden

+46 13 28 24 93
+46 13 14 22 31 (fax)

 

[Roedy Green]

Primarily the Deluxe Doclet gives you faster API, with an organization
designed for programming and for successfully pairing very good
overview with quick and easy access to detail. Based on in-depth
research of API design. Try it out!

I tried it. I did not notice any major differences from the HTML Sun
generates. What did you do different?

 

[eribe]

Did you go look in the class document?

The idea was to reorganize the class documents and put methods on top
(avoiding having to scoll down every time, past text about classes you
already know). Details were moved into hidden, expandable section for
use when you yourself want to - the result a more compact design with
easy access to detail. Click on the class and method links to open
expandable sections.

 

[Andrew Thompson]

On 24 Oct 2005 01:50:52 -0700, (e-mail address removed) wrote, quoted or
indirectly quoted someone who said :

LOL! ;-)

I tried it. I did not notice any major differences from the HTML Sun
generates. What did you do different?

It compacts entries (methods, attributes, constructors)
and allows 'click to open' - I suppose it might lose the
effect if JS is disabled, but.. then...

No. It is not the effect that is lost, it is the information!

Instead of 'degrading gracefully' to an expanded form, it
becomes inoperable (only the entries are listed, clicking
does not change anything).

(shrugs) The icon is pretty..

 

[Andrew Thompson]

..Details were moved into hidden, expandable section for
use when you yourself want to - the result a more compact design with
easy access to detail.

Do it a slightly different way and you can have a document
that 'degrades gracefully' for non JS clients. The best
of all worlds.

Are you interested?

 

[eribe]

Yes, that is true. You do need JS to take advantage of the features in
the Deluxe Dcolet.

Sure, I'm interested. What did you have in mind for the non-JS users.

 

[Andrew Thompson]

Yes, that is true. You do need JS to take advantage of the features in
the Deluxe Dcolet.

Sure, I'm interested. What did you have in mind for the non-JS users.

Simple to describe, a little trickier to implement*.

Initially present the content as 'visible', but 'onload',
iterate the elements and make them invisible.

That way, non JS users will at least get the conent in it's
visible form, while JS enabled clients will see the document
appear quickly then 'squish down' to the compact form.

* ..but the 'devil is in the details. Note that you can
probably also have the links act purely as anchors when
JS is disabled, but I suspect that would require a slight
redesign of the structure (I did not look at it too closely,
but most things are possible while your Doclet is amendable).

In any case, it is rather dangerous getting JS advice from
Java programmers, since they generally cannot program it,
...but mistakenly think they can.

For the details of this (as well as probably 10 more tips)
I recommend you go to the place where they swim in JS..
<http://groups.google.com/group/comp.lang.javascript>

HTH

 

[eribe]

Yes, that was what I had in the DJavadoc research platform which
started back in 1999 http://www.ida.liu.se/~eribe/djavadoc. But since
quick access and compact design is the point of Deluxe Doclet I would
not want to slow it down every time you look at the page using JS by
collapsing section afterwards. Perhaps there is a neat way of changing
CSS style sheets and to make that distinction without it affecting the
performance.

Erik

 

[Andrew Thompson]

..Perhaps there is a neat way of changing
CSS style sheets and to make that distinction without it affecting the
performance.

How about two different stylesheests?

Write the import for the JS enabled styles (initially invisible),
using JS itself. You might simply add that after the 'no JS'
stylesheet, or try calling the no JS stylesheet in the <noscript>
element..

But there I go, musing about JS implementation.

...Didn't I *warn* you about people like me?!? ;-)

 

[Roedy Green]

Did you go look in the class document?

So you get the one line summary, that instantly expands to the full
detail without losing your place in the one-line summary. It is still
visible with any left over screen real estate. The one line summary
lets you see the big picture more easily. Further the expanded view
is in alpha order, not "random" as now.

That is probably a good thing. Often the short summaries are
misleading.

I wonder if someday there will be a way to organise it like this.

1. on each the method/class there is a wiki entry where people can add
additional notes, sample code, gotchas etc.

2. Individual people may share their annotations, with ways of not
having to start over with every new release.

 

[=?ISO-8859-15?Q?R=E9mi?= Bastide]

For a more luxurious Java API experience.
http://www.ida.liu.se/~eribe/deluxe

Nice, but what about JDK1.5 generics... Do you plan supporting this ?

 

[Roedy Green]

The idea was to reorganize the class documents and put methods on top
(avoiding having to scoll down every time, past text about classes you
already know). Details were moved into hidden, expandable section for
use when you yourself want to - the result a more compact design with
easy access to detail. Click on the class and method links to open
expandable sections.

here is how it works under the hood using JavaScript -- toggling
blocks of code between two styles, invisible and block.

<span onclick="if
(this.nextSibling.nextSibling.style.display=='block') {
this.nextSibling.nextSibling.style.display='none';} else
{this.nextSibling.nextSibling.style.display='block';};return

 

[Roedy Green]

LOL! ;-)

People are always bawling me out for screwing up attributions. That's
the lawyer version of an intro line.

 

[eribe]

That's possible in other systems, like the PHP manual and I
personally think it is a great idea and it is in the future for Deluxe
Doclet. Getting forums to hook up to reference documentation in
general, bug databases and other relates sources.

 

[eribe]

There were major updates in the Standard Doclet design in 1.5 and
therefore I had no time to update for those changes yet. I don't know
if there will be particular problem with generics besides compiling.
You should be able to run the Deluxe Doclet with java 1.5 as long as
you use the 1.4 tools.jar file.

 

[Chris Smith]

For a more luxurious Java API experience.
http://www.ida.liu.se/~eribe/deluxe

You have a serious problem with deprecated methods. You can't even tell
that they are deprecated at all until you click on them. This makes it
even harder than usual to use the API docs for java.util.Date, for
example.

I'd like to see movement in the opposite direction. You should have to
click on something to even see the list of deprecated methods.

--
www.designacourse.com
The Easiest Way To Train Anyone... Anywhere.

Chris Smith - Lead Software Developer/Technical Trainer
MindIQ Corporation

 

[eribe]

In the DJavadoc doclet http://www.ida.liu.se/~eribe/djavadoc you could
set a filtering on deprecated making them grey. I could go for color
coding in that same way to single out deprecated methods. Check it out
and tell me what you think.

 

[eribe]

Actually, what you do get is the member signature. The one line comment
that used to make the summary twice as long is now removed (its part of
the details). I find it gives better pattern recognition.

 

[Real Gagnon]

I wonder if someday there will be a way to organise it like this.

1. on each the method/class there is a wiki entry where people can add
additional notes, sample code, gotchas etc.

2. Individual people may share their annotations, with ways of not
having to start over with every new release.

JavaLobby has set up a site a like that : http://jdocs.com/

Where "users can contribute their own notes to virtually any class, field,
method."

Bye.

 

[Roedy Green]

That's possible in other systems, like the PHP manual and I
personally think it is a great idea and it is in the future for Deluxe
Doclet. Getting forums to hook up to reference documentation in
general, bug databases and other relates sources.

Wow, yes! Integration takes a lot of work to pull together, but it
greatly magnifies the power of the individual pieces. And when it is
complete, it looks is if there was no effort -- very Taoist work.