Skip to main content

Documentation enhancements

24 replies [Last post]
denismo
Offline
Joined: 2003-06-28
Points: 0

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.

Reply viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.
javakiddy
Offline
Joined: 2004-01-23
Points: 0

I think the solution is to have a single Wiki, but allow 'entries' to be tagged with which versions of the Javadocs they apply to. Then allow some kind of filtering mechanism when a page is displayed. Say for example I contributed something for Tiger, and tag it as "1.5+". Along comes Mustang, and my contribution is no longer applicable, so someone simply changes the tag to "1.5", which means it will be filtered out when viewed by Mustang users, but still visible to Tiger users. (Hopefully the page would contain a mechanism to manually change the filter.)

Such a system would also allow Wiki entries for legacy versions of Java (although obviously old Javadocs do not contains links directly to the Wiki).

denismo
Offline
Joined: 2003-06-28
Points: 0

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.

cowwoc
Offline
Joined: 2003-08-24
Points: 0

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.

tim12s
Offline
Joined: 2004-02-02
Points: 0

+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.

brucechapman
Offline
Joined: 2004-03-18
Points: 0

Javadocs are pretty good. I trust javadoc API documentation much more than many other forms of API documentation. However, there haven't been any fundamental changes to the browsing experience since its inception. Our "hare" has been asleep, basking in its lead, but it is probably time to wake up and make some more advances lest the tortoises plod on past unbeknownst.

One of the problems with the current API docs, is that there is no distinction between what is "core" to the API, and what is there as "icing on the cake", to cover the rarer use cases.

By core I guess I mean the 10% of the methods and classes that get used 90% of the time (or 20%/80%).

The "core" classes in a package, and the "core" methods and constructors in a class are the ones that are most likely to appear in a succinct example, they are the essential things needed to use the API in a simple case. They are the things you need to understand first in order to use the API.

I am rambling on about this because the concept is a little subjective, but you hopefully all get the point.

As a potential solution to this, or at least as a starting point, I offer the following...

What I have tried is a small taglet and two tags to try and overcome this problem.

I use a @core tag to indicate the core classes and methods.

In every class's javadoc I put a @corelist tag, where I want a list of the core declarations related to this class.

What the taglet does is generate at the @corelist tag a list of all the core declarations in this package that use this class in some way. This list is broken into three categories
* Obtain
* Modify
* Use

"Obtain" lists the methods and constructors that are marked as @core and return (or construct) an instance of this class (or a subtype of this class/interface). A core constructor, a factory method in another class, or a static factory in this class would all be included here.

"Modify" lists the core methods in this class with a void return type.

"Use" lists other @core methods and constructors in this package that use this class as an argument type.

The lists only contain things in the same package (imagine what the @corelist would look like for String if this were not the case).

I put a @corelist in the package javadoc, and that lists the @core classes in the package.

With this, I am able to see immediately which classes in a package are @core. Further, for any class, whether or not it is a @core class, I can easily answer the questions
* "How would I normally get one of these" ("Obtain")
* "How would I normally configure it to my needs" (Modify)
* "What is the common ways to use this class once I have one" (Use)

If this mechanism were to be implemented in the standard doclet, the @corelist tag would not be required since the doclet would generate a corelist at the appropriate place for every class.

API writers would merely have to identify the @core classes and methods and constructors, and tag them with @core.

In a package that I tested this on, without spending too much time marking things as core, this yielded a very valuable web of links summarising the package. The package had a singleton service provider through which all other objects were obtained, but often indirectly. This was very apparent from the core links, but not at all obvious in the original API unless you browsed the whole package.

denismo
Offline
Joined: 2003-06-28
Points: 0

Very interesting suggestion

jtr
Offline
Joined: 2003-06-10
Points: 0

1) more examples in the javadocs. Just a pointer to the java tutorial pages would be better than nothing. Many of the MS docs have little code examples and that makes things just a little bit easier.

2) A picture is worth a thousand words, especially for graphics and component APIs. Again, links to the java tutorial might be OK here too.

3) Inexperienced developers often don't realize that some resources need to be disposed(). It would be great if:
a) ALL resources that need to be freed use a consistent API (dispose(), close(), etc...) you pick one
b) This API is explicitly called out in the javadoc
(a) is better than (b) but either or both would be great.

pdoubleya
Offline
Joined: 2004-02-09
Points: 0

I agree, there needs to be better integration of API docs and samples.

The Java tutorial is a good place to start, but I think we can do better. MSDN has been good about this, for example for VBA documentation: when describing an API, they almost always have a small, usable code sample that shows a working example.

This would be a lot of work for the documentation team, but the current situation is a lot of trouble. You have to identify the API that is relevant, check to see if there is a tutorial entry, check for a sample in the JDK, read, test, etc.

If we could more easily cut-and-paste a sample and test it right away, that would be much preferred.

Patrick

monika_krug
Offline
Joined: 2004-10-14
Points: 0

JavaDoc about classes other than collections that use generics should be more extensive (examples would be good), as this can become pretty confusing.

Example: Class
Class asSubclass(Class clazz)

I don't get it, does this method have two return types? and Class? Certainly not. According to the description, the return type is probably Class ... but what is the doing there in front?

The JavaDoc about this method does not even include T and U. That would probably clarify it.

(This is the JavaDoc for the method:
Casts this Class object to represent a subclass of the class represented by the specified class object. Checks that that the cast is valid, and throws a ClassCastException if it is not. If this method succeeds, it always returns a reference to this class object.

This method is useful when a client needs to "narrow" the type of a Class object to pass it to an API that restricts the Class objects that it is willing to accept. A cast would generate a compile-time warning, as the correctness of the cast could not be checked at runtime (because generic types are implemented by erasure).

Returns: this Class object, cast to represent a subclass of the specified class object. )

pdoubleya
Offline
Joined: 2004-02-09
Points: 0

As a developer, the main problem is really with multiple APIs, as others said. As a developer, I now use a couple of dozen FOSS APIs on a regular basis, for different projects. Their JavaDocs are not linked to each other, there is no real search capability, and installing new docs means I have to update my references to the API docs.

The second problem is with the size of the JDK documentation download. Because it is in HTML, installing documentation is a hassle, as is figuring out which documentation you have installed if the docs don't clearly state the version.

My suggestion is to keep the HTML version for standard use, but to support a new JavaDoc toolkit based on something like Ashkelon (http://ashkelon.sourceforge.net/). Ashkelon indexes all APIs using a doclet into a relational database. It then provides lookup mechanisms, and a set of JSP pages to read from these lookups and provide searches.

You can load one or more APIs and if there are cross references between the packages, these are automatically linked in the database (e.g. any 3rd-party library that references java.lang.String will reference the JDK API). Linking is not just on inheritance, but on return values, parameters, interfaces...and the search mechanism allows for searching on any of these aspects of the code.

If Sun could throw support behind this sort of approach, Ashkelon could be extended with a REST/SOAP download mechanism so that new APIs could be downloaded easily as needed. They can also be culled from the source code.

The output could be in a browser (dynamic using JSP), or HTML could be produced (for travelling) or a viewer could be used in Swing. So--static and dynamic output in a variety of output styles. There might even be new business opportunities for "skinning" the display of the documents.

You can also use the API to provide for some utility functions across IDEs--for example, generate a stub of an interface implementation or extend a class, etc.

Advantages
1) Can host multiple APIs, including new extension packages from Sun, 3rd-party FOSS and commercial libraries, with automatic linking

2) Can pull down new APIs docs as packages are loaded, either from the web or by scanning the source using a doclet

3) Multiple output formats--could generate HTML, XHTML, XML, PDF, or view in a rich client

4) Clear view of dependencies between packages

5) All sorts of searching supported--Ashkelon lets you find any method that returns JTree or other class, for example

6) Storage in any relational database, allowing for team/corporate, centrally-maintained API docs for internal reference

etc.

The Java community is now expanding beyond Sun and commercial vendors to include a large and vibrant FOSS community. Developers will use more and more APIs and need a single way to view, index, and search them without trouble.

Obviously we can use FOSS tools like Ashkelon ourselves, but having a standard API for this, and a standard doclet backed by Sun, would encourage this newer, improved form of API documentation.

Patrick

monika_krug
Offline
Joined: 2004-10-14
Points: 0

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.

cowwoc
Offline
Joined: 2003-08-24
Points: 0

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

cowwoc
Offline
Joined: 2003-08-24
Points: 0

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.

tim12s
Offline
Joined: 2004-02-02
Points: 0

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.

brucechapman
Offline
Joined: 2004-03-18
Points: 0

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

denismo
Offline
Joined: 2003-06-28
Points: 0

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?

brucechapman
Offline
Joined: 2004-03-18
Points: 0

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.

mgrev
Offline
Joined: 2003-08-12
Points: 0

Couldn't the comments be tagged obsolete or "hidden" by the guys that fix the bug. They can check the wiki (since it's @ Sun) and don't delete it, but mark it "obsolete as of 1.5.1_02" or something to that effect.

Cheers,
Mikael

tim12s
Offline
Joined: 2004-02-02
Points: 0

I _really_ dont like the idea of a Wiki that is pinned against javadocs. I want editable documentation that sits next to javadocs that covers stuff not related to the API. Understand the difference between API documentation and a HOWTO or a FAQ. They both might refer to API documentation but its definately _NOT_ pinned against the javadocs.

Sticking to fixed articles that can be extracted from javadocs (eg: A description on configuration parameters and boundaries, how the thing's going to 'fail') or included with documentation is good. While the doc-files directory partially solves this problem, there is a need to merge the JavaDocs with a bigger website. Articles should come up as articles, javadoc api docs as javadoc apis, FAQs, HOWTO, etc.

In addition, after each release, if articles are focused on a particular topic it would be easier to review each article in order.

A wiki requires localised topical conversation (Admittidly, Hibernate does well with its wiki) and I can easily see things expanding pretty quickly into something unmanaged.

opinali
Offline
Joined: 2003-06-17
Points: 0

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.

jodeleit
Offline
Joined: 2004-10-26
Points: 0

> And I want a single index in the left frames, in the
> Overview, Tree and Index pages, with every API from [..]

This was (one) intention behind JDocs.com but SUN forced them to remove their api's..

zander
Offline
Joined: 2003-06-13
Points: 0

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.

pprun
Offline
Joined: 2004-07-01
Points: 0

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

jarouch
Offline
Joined: 2004-03-04
Points: 0

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.