 |
 | Home | Contact Us | FAQ | Search & Site Map | Link to Us |
 | Sign In | Join | Other 45 Sites in Network |
Java Forum / General / October 2005Free Deluxe Doclet - alternative Javadoc design
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) >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?  SignatureCanadian Mind Products, Roedy Green. http://mindprod.com Again taking new Java programming contracts. 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. > ..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? 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. > 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 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 > ..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?!? ;-) >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. SignatureCanadian Mind Products, Roedy Green. http://mindprod.com Again taking new Java programming contracts. 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. >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. SignatureCanadian Mind Products, Roedy Green. http://mindprod.com Again taking new Java programming contracts. 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. -- Erik Berglund (Ph.D.), www.ida.liu.se/~eribe Adjunct Associate Professor (Senior Lecturer) > I wonder if someday there will be a way to organise it like this. > [quoted text clipped - 3 lines] > 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. SignatureReal Gagnon from Quebec, Canada * Looking for Java or PB code examples ? Visit Real's How-to * http://www.rgagnon.com/howto.html >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 SignatureCanadian Mind Products, Roedy Green. http://mindprod.com Again taking new Java programming contracts. LOL! ;-) >>Primarily the Deluxe Doclet gives you faster API, with an organization >>designed for programming and for successfully pairing very good [quoted text clipped - 3 lines] > 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.. On Mon, 24 Oct 2005 10:06:33 GMT, Andrew Thompson <seemysites@www.invalid> wrote, quoted or indirectly quoted someone who said : >LOL! ;-) People are always bawling me out for screwing up attributions. That's the lawyer version of an intro line. SignatureCanadian Mind Products, Roedy Green. http://mindprod.com Again taking new Java programming contracts. > 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 ? SignatureRémi Bastide http://liihs.irit.fr/bastide 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. > 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. Signaturewww.designacourse.com The Easiest Way To Train Anyone... Anywhere. Chris Smith - Lead Software Developer/Technical Trainer MindIQ Corporation 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. >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. Maybe you can paint them in brown. SignatureCanadian Mind Products, Roedy Green. http://mindprod.com Again taking new Java programming contracts. > For a more luxurious Java API experience. > http://www.ida.liu.se/~eribe/deluxe Sadly my experience was far from luxurious. (1) Requires far too much clicking (2) Hides too much information. (3) Expanding nodes cause content to shift constantly; requiring more memory load just to refocus eyes. Finding relevant part of API with standard javadoc is much easier, since, (a) less clicking, works with keyboard much better (b) scanning of text is faster, since spec is directly visible (c) search functionality works SignatureKI A matter of taste, I suspect. My research indicates that the reorganisation and compact design with expandable sections is the desired design. But it doesn't mean that other designs isn't better for other purposes. I see the Deluxe Doclet as an alternative for the Standard Doclet, built for speed and focusing on putting the most frequently used information closest to the user for users that work with Javadoc documentation when they program. The Standard Doclet is out there for the ones that read classes once and then use more code completion systems in IDEs to find methods and so forth when programming. You should pick what you like. >A matter of taste, I suspect. It also depends what you doing. If you are reading about the class for the first time, you want to read everything top to bottom. If you are looking for something you know must be in there and you know roughly its name or signature, the one liner lets you find it by rapid scan. SignatureCanadian Mind Products, Roedy Green. http://mindprod.com Again taking new Java programming contracts. > I see the Deluxe Doclet as an alternative for the > Standard Doclet, built for speed and focusing on putting the most [quoted text clipped - 3 lines] > completion systems in IDEs to find methods and so forth when > programming. Perhaps you could have an "expand all" link/option on the page for use when someone wants to see the documentation as a text rather than as a map. (BTW, I like your doclet format) -- chris An idea is to double the pages, run the Standard Doclet and the Deluxe Doclet in parallell and then alow for switching like you say. -- Erik Free MagazinesGet these publications absolutely FREE for up to 12 months. There are no hidden fees and no obligation. Simply choose a title, complete the application form and submit it. Read more ...
|
Reply to this Message
|
 Sign In
 Join
 My Latest Posts My Monitored Threads My Blog My Photo Gallery My Profile My Homepage Start New Thread Enable EMail Alerts Rate this Thread
|
©2009 Advenet LLC Privacy Policy - Terms of Use
This website includes both content owned or controlled by Advenet as well as content owned or controlled by third parties.