Documentation enhancements - Java SE (Archived)

Do you think that documentation (JavaDoc) is not sufficient? That it lacks some general information? Too restricted? Hard to find the things? We'd like to hear your complaints and suggestions.

Connection of documentation and RFEs can be good i think.
Possibility to see enhancements of api in context of documentation and other RFEs for parts around can be helpfull.

More pictures...
For example (and I suggested this to the Java2D guys a year ago already) the Graphics object does rotations around an coordinate system that is not intuitive.  Simple posting a couple of pictures at the right spots would make many be able to understand this stuff a whole lot faster.

The major problem in javadocs is the lack of integration btw documentation sets from multiple APIs.  For example, while reading locally J2EE docs for Javax.servlet.Servlet, getServletInfo() contains a link to java.lang.String which is in the J2SE docset. But the link sends me to the online docs for J2SE 1.4.2 at Sun's website.  I really wanted to jump to the local documentation for J2SE 5.0, also installed in my machine.  And I want a single index in the left frames, in the Overview, Tree and Index pages, with every API from J2SE, J2EE, J2ME, and also *all* other Sun APIs that are not included in any of these J2*E platforms. Please produce a single monolithic doctset with ALL the APIs and update it whenever ANY single API is updated. Even if that means updating a 200Mb bundle every month. Do the same with all your tutorials, and make them more integrated with the javadocs.  Cross-reference stuff so if I'm reading the javadocs for Servlet.getServletInfo(), I can easily jump to any tutorial, demo, or guide that explains or uses this particular API.  Of course this is a huge work, not viable to do manually, but I guess you can do some automated scanning of the existing materials.
This brings in the second major problem: HTML browsers are not a good host for huge, complex docsets. Please move to a JavaHelp-based viewer so we also get decent index and search and other features that can be programmed easily with JavaHelp -- like clicking a button to run some demo, or presenting crodss-references (like all tutorials and demos that use some API) as popups, etc.

java tutorial may be include the sample of new APIs and reflect new languag feathers.
Remove those prior to jdk1.1 out.

Current javadocs are absolutely insufficient.  I've written Doclets to extract design documentation (not API documentation) from a source tree.  I strongly believe that ALOT more could be done with javadocs.
(1) Firstly, alot of javadocs are out of date, or just not sufficient.  I have commonly read documentation which tells you about settings and properties without going into specific details.  The end result is the need to drill down into source code.  (I'm refering to JDK docs here).
(2) The standard doclet should be extended to allow package comments, method comments and in-source comments to generate 'articles'.  These articles should allow related topics to be detailed where they are appropriate and are then stiched together during javadocs and could cover configuration parameters, executable parameters, etc to be configured.  It makes alot of sense to have the documentation of certain types of information inside the javadocs as close to the code as possible.
(3) Some sort of 'Article' standard is required.  While not related to javadocs, definately documentation related.  The MSDN provides a certain level of quality documentation and the fact that all documentation for their products can be found on the MSDN.  I would recommend trying to use some sort of standard to allow various technologies that meet certain standards of documentation to have their user manuals and integrated into some sort of developer network.  (The Java Technology Developer Network).
I would like to see something similar to jdocs.com but for user manuals, articles, HOWTOs, bug reports, etc.
JGuru, JavaPractices.com, javaalmanac.com, JDocs, etc should all be integrated.  There are technical, copyright and practical issues that would need to be solved before integrating the various documentation sources for java.
(4) Create a search 'applet' that allows javadocs to be offline searchable.

Denis,
We should have the ability to file RFEs against the Javadoc *directly off the Javadoc page*. That is, say I spot a mistake in the documentation or need it clarified, I should be able to file a RFE with the suggestions text to be inserted and a Sun engineer would simply accept/reject it. It would improve the turnaround time for these kinds of issues.
Gili

Good points Tim.
I was thinking about this, and it seemed that it would be nice to be able to share our "articles".
Then it just occurred to me, that what might work really well, is if every entity in the javadocs (package, class/type, method, field) had a link to its own wiki page at SUN.
If you found something improveable in the docs, click thru to the wiki page and make a note there.
If you write a simple example, put it in the wiki.
If you are bamboozled, read the wiki.
If you find a tutorial that is really helpful, link to it from the wiki.
If you file a bug against something, link to the bug in the wiki.
If you work at SUN and want to improve the documentation, read the wiki.
Sun Build a separate set of api docs where the links go to a static copy of the wiki at build time, bundled with the javadocs (for those without "always on" internet connections). Those static copies could have a link to the live wiki (for when they are "connected" and want to see the latest incantation of the page). Maybe monthly updates (possibly incremental) to the static wiki set, could be released, so they could be downloaded and spliced into the existing docs.
Bruce

BTW: I want to note, Sun wouldn't need to write any special code to make this happen. To my recollection, there are already mature open-source packages out there that do this. Sun would simply need to install it on their servers and give it a whirl.

The problem of turn-around time is not related to Sun engineers not being able to notice documentation problems. Right after you filed doc problem bug, we are ready to fix it (if it is really a problem). There are procedural comlexities that do not allow us to fix such problems until the next major release of Java appears.

Yes, I think it is a nice idea, I'll try to move it forward.
One problem I see with it - what happens with user doc comments between releases?

Denis,
That is not a problem. Here is what I expect from Sun:
The latest stable release is JDK 1.5
The current development release is JDK 1.5.1
I file a RFE against documentation found in JDK 1.5
Sun fixes it in the JDK 1.5.1 documentation
This is perfectly acceptable *as long as* you make the JDK 1.5.1 documentation available while it is being developed. One of the things I really enjoyed about the JDK 1.5 development was that while it was in beta I had free access to the documentation and see my suggestions affecting the final product. This was a big moral boost for me.
I hope such a procedure is acceptable to Sun. Allow us to file RFEs, fix the problems immediately, and make them available online under the guise of the unofficial documentation for the upcoming release.

Do you mean, when a new release is made?
If so, then I guess the doc writers need work with both the offical javadocs, and the wiki. If they take on board stuff from the wiki, then the wiki should have that removed (since its now in the javadocs).
Actually theres a gotcha there too isn't there. We don't want the tiger comments in the wiki deleted just becuase they have been fixed/incorporated etc in mustang. I guess the solution is to have a wiki for each major release, with a carefully considered point at which a copy of the wiki is made. Either that or use CVS behind the wiki and do branching stuff, the mustang wiki is a branch off the tiger wiki. manage the wiki as you would the code under CVS.
Sure its not quite trivial at new release time, but certainly not unresolvable.

+1
Note, this isnt a code release but a documentation release.  Some form of online interactive documentation mechanism can only help aslong as it isnt freeform and leads to documentation that is difficult to manage.

I think JavaDoc is pretty good and most things are easy to find.
Some things are not specified thouroughly / easy to find, e.g. ArrayList.remove(o) and ArrayList.contains(o) - the JavaDoc does not state whether the comparison is done via .equals or via ==; only when navigating to List or Collection one finds the statement that it is done via .equals (except for null, then via ==). In this case either the JavaDoc for ArrayList should be completely empty so that one automatically clicks on the link under "specified by", or it should be complete enough to at least include this essential information.
Also, there could be more links to tutorials for complicated topics. There are tons of links for Swing, but e.g. no link from any java.lang.reflect classes to the reflection tutorial.
The following has nothing to do with Mustang or J2SE: All API JavaDocs should be available for browsing online, too. The J2ME API JavaDocs are currently only available for download as a zipfile. That can be a pain when working in varying locations.

Related

Why do URLs in documentation have to change??

Hi,
I find it really frustrating when the URLs in Sun-produced text books are broken.
This is inexcusable! Rather than break them, there should be a pointer to the new version of the topic and a pointer to the archived original topic.
As an recent convert to Java, I have been buying the textbooks from Amazon marketplace. One of them came without a companion CD and it has been quite difficult tracing the curren online versions of, for example, the Java Cryptography specification (Now renamed to JCE) and the Drag & Drop spec looks like it is still in revision state!
Not only that but the web site has links to ftp.java.sun.com which no longer appears to exist!
Please, Sun, try to keep some consistency with your links and terminology!
Brian 
This is not the way to contact Sun. This only contacts other forum users like yourself.
You may just as well written a complaint on a piece of paper and flushed it down the potty. In fact that would have been better, because that way you wouldn't have wasted some forum resources.

RFC: JavaDoc + Wiki

Hello Java-Friends,
I would like to ask for your feedback on an idea for an JavaDoc
enhancement:
Imagine that you could edit each JavaDoc comment on a JavaDoc site like
http://java.sun.com/j2se/1.4.2/docs/api/ using the wiki command "edit".
Changes that you make to the comment get directly reflected both on the
html page and in the underlying source-code.
With a Wiki you get the following advantages:
- Open for user collaboration
- Version control to rollback to better versions (for instance
because of vandalism)
- Proven, known and popular interface (just think of
www.wikipedia.org).
Reflecting the changes from the JavaDoc page back into the source-code
has the following advantages:
- Contributing to your favorite APIs is now much easier.
- Users can be asked to collaborate:
- For instance after a user asked a question on a mailing-list it's
now possible to ask the person to contribute the solution s/he got on
the mailing-list to the documentation.
Of course there are also disadvantages:
- It could be difficult to accumulate enough users to reach critical
mass.
- The quality of the documentation could be rather bad.
Implementation should be not to difficult as both JavaDoc and Wikis are
well established technologies.
Please let me know whether you think this is feasible and useful.
Can you imagine using such a system?
Would you mind if your own API was using the system and users would
change comments you have written?
You can find a mockup-walk-through at:
http://page.mi.fu-berlin.de/~oezbek/cgi-bin/view/Docu/WikiDoc#Mockup_...
...and a use case for an Open Source project at:
http://page.mi.fu-berlin.de/~oezbek/cgi-bin/view/Docu/WikiDoc#Use_Sce...
Thanks you for your comments,
Christopher 
I do occasionally feel that I want to edit a Sun Javadoc page, but normally only minor edits - closing unclosed <code> tags, in particular. Possibly of more use would be something like the php doc's comment feature. See e.g. http://www.php.net/manual/en/ref.http.php 
Possibly of more use would be something like the php doc's comment
feature. See e.g. http://www.php.net/manual/en/ref.http.phpYou know that this is possible at sites like JDocs and the like ... unfortunately Sun does not allow that the API docs for the JDK are hosted at such sites, too. 
I understand Sun's problems with making Java open source and WikiDoc would therefor aim rather at open APIs like for instance the GNU Classpath API.
The biggest problem I see with a page like JDocs is that their centralized approach prevents comments to really get incooperated into the source. At JDocs the comments are also quite spare and don't seem to have reached the critical mass required to make a community effort work.
http://www.KickJava.com is another example of how the idea could maybe work.
Thanks for the link to the php-Manual! Which brings up another question:
* Would you rather want to be able to discuss a API element? (JDocs, PHP-Manual)?
* Provide examples (KickJava)?
* Edit the JavaDoc comments themselves (Wiki)?
Thanks for your input!
Christopher 
You guys might be interested in checking out http://jsourcery.com which integrates javadocs and source code. You can even trace program execution by clicking on the hyperlinked source code.

javadoc.org ?

Hi,
I think this is a good forum to get feedback on an idea. Javadoc is clearly one of the factors that has led to the success of Java. I find Javadoc much easier to read and understand that Microsoft documentation.
However, it pains me that most of the time you have to download Javadoc in a zip file, install it on your PC and then read it locally. I always appreciate it when companies put their API documentation online so that I can do a quick google to find it.
My idea (and it may well not be original!) is to have a central http://www.javadoc.org website.
The website would be divided into 3 streams: J2ME, J2SE and J2EE. The core API documentation of the most recent version of each Java platform would form the base for the website. Then companies and organisations such as Jakarta, Oracle, Sybase, MySQL, all the people on Sourceforge etc. etc. would submit their Javadoc to the site. When submitting Javadoc, each organisation would specify which of the Java platforms (J2ME and/or J2SE and/or J2EE) the API corresponds to.
There would be a nightly build to update the interface with new API information that had been submitted during the day.
You would end up with a completely interconnected Javadoc interface for all the APIs you're likely to want to look up. E.g. If you're doing J2ME development you'd be able to see the MIDP 2.0 profile API documentation along with the JSR-82 Bluetooth documentation and the core J2ME documentation... all in one place!
Companies obviously wouldn't want to submit their .java files so it would be more appropriate to have a 2 phase approach to creating the Javadoc. The companies would run a pre-parser which would extract the Javadoc from .java files and place the results into an XML file. This file would be submitted to javadoc.org and would be included in the nightly build.
There's no need to worry about versioning. I'm fairly sure that just having the most recent version of every API linked together (and discarding older ones) will give a 99% accurate result. Generally, developers only want to know the latest specification. For example, if I am developing servlets to the 2.1 specification, it really isn't a problem to use the 2.4 specification documentation. Sure, some of the method calls are new... but the "since" feature of Javadoc helps you with that.
Anyway, good to get that off my chest. Please let me know what you think.
Cheers,
Dave
(http://www.emobus.com) 
This is a good idea and one that we have thought about doing.
Someone has released code to do something similar to this,
described at:
http://java.sun.com/j2se/javadoc/faq/index.html#ashkelon
We have not chosen to put our javadoc-generated docs there.
-Doug
Hi,
Many thanks for that. Good article at:
http://java.sun.com/features/2002/07/dbdoc.html
However, dbdoc.org seems to be "closed for business". The website is unavailable.
Ashkelon seems to be a fairly ambitious project. Something a bit simpler, just an integrated snapshot of multiple APIs, should be more achievable especially with the -linksource improvements of Javadoc 1.4.
A project such as this would really need Sun's buy-in to make it a success. The root of all of the Javadoc is, of course, the core Java APIs of J2SE, J2EE and J2ME.
Regards,
Dave 
Is there a way to force JavaDoc to output links to packages even if the package isn't in an available source tree? Because the main problem with JavaDoc I'm finding, is that package A links to package B, and package B links to package A, so I am forced to JavaDoc them at the same time, which is a pain, and sometimes impossible if I don't know ahead of time that I'm even going to use package B.
(e.g. DOM4J would link to JDOM, and I might have installed DOM4J without knowing about JDOM yet, then discovered JDOM and installed its JavaDoc, then wondered why the links don't work.)
If I'm right in what I'm thinking, Ashkelon does resolve this particular issue by storing all links and then only displaying the link if it is available. I could be wrong.
Anyway it sounds like a killer app, if only I could get it to read the 1.4 source files without throwing all sorts of errors.

Use of classes in com.sun.tools.doclets

Hello -- What is the best practice recommendation wrt using the classes in com.sun.tools.doclets -- particularly with the planned refactoring?
I'm writing a doclet that doesn't subclass, say, the standard doclet. There are obviously several very useful classes in this package (ClassTree, Util, MethodFinder, etc.) that I'd like to use. I can simply call their methods, but I'm curious to know if their active days are numbered.
Would it be better to simply incorporate the source? What are the restrictions on using the source in my own doclet?
If this is all covered somewhere (I've been hunting around a bit), please feel free to simply point me to the info.
Thanks!
Steve 
The Java 2 SDK license (which covers javadoc) allows you to only
redistribute the code unmodified.
In 1.5.0, the refactoring has renamed all of the packages and
moved a lot of code around. We hope and plan to release
the refactored code on java.net around the time 1.5.0 is
released, and get an early access of it out. We'll notify
people who are on the javadoc-announce email address which
people can sign up as described at:
http://java.sun.com/j2se/javadoc/#forum
If you want more specific information now about how these will change,
please let me know and we can answer those questions.
-Doug Kramer
Javadoc team

Ant tasks

I feel there should be better documentation for an Ant tasks, current one is outdated and spread around javadocs.
For instance, the font task that has changed in 1.2.1 removing support for src="font.ttf", this change is nowere to find, and the javadocs for Font class still mention it.
What's worse, the task itself now silently ignores this attribute and does not produce bitmap font. However, there is no error message produced of any sort.
Also, is there any chance opensourcing at least Ant  tasks?
Yep, thanks, I've figured that out after some googling. It's just I'm unhappy about state of ant tasks/docs.
I know, I know. With all the minor issues LWUIT is stll the best UI toolkit in j2me world for now. So big thanks to developers, hope they'll do their best.
Anton
Relatively to most OSS projects I think our docs are pretty reasonable... Especially considering the fast pace of change here (the project is not that new but it is evolving rapidly).
The Ant task was rewritten from scratch for 1.2.x so obviously there were holes in the new docs. We would be very happy if community members would step up and contribute information in this regard... However, notice that you can google most issues you experience in LWUIT to find an answer very easily.
BTW our developer guide has over 100 pages and we added quite a bit for 1.3, there is also a 3rd party LWUIT book already published and widely reviewed.
Fair enough. BTW, does becoming any sort of contributor requires signing and faxing that doc?
You can scan and email a signed SCA to lwuit at sun dot com. This is required for all contributions, docs as well.

Categories

Resources