Kathy Walrath's Blog

J2SE Archives

Javadoc: How Do We Improve It?

Ten days ago, a survey came out aimed at people who use the automatically generated API documentation for the Java platform. (Many people call this the javadoc, but, strictly speaking, that's just the name of the tool that produces the API doc.) Amy Fowler blogged about the survey back then, but we want still more responses. So, if you haven't already...

Please take the javadoc survey!

It's short. It's sweet. It's your chance to influence the direction of javadoc. Even if you've already given feedback via comments on Amy's blog or mine, please take the survey so your votes can be counted and all the feedback kept in one place.

How can you pass up a chance to answer these questions:

• What source of information (online doc, book, article, forum, etc.) have you found to be the MOST useful for doing Java development?
• Which way do you prefer to view J2SE generated API documentation?
• Which of the following questions would cause you to consult the J2SE generated API documentation FIRST?
• Who's funnier, Stephen Colbert or Jon Stewart?

Maybe that last one's not really on the survey, but the fact that you've read this far means you certainly have the attention span the survey requires. So how about it? Take the survey!

The Java Tutorial: Updated at Last!

Almost a year since its last revision, The Java Tutorial has been updated again. Most of the changes are in the basic trails — the ones all new programmers might need. But even if you're not a beginner (actually, especially if you're not) the Tutorial team would like your feedback on the new stuff.

The history page says what's changed. Most of the differences aren't terribly noticeable — minor updates from 1.3 to 5.0, new figures, etc. However, there are some new pages the team would like you to check out. They include:

Working with Manifest Files: The Basics

A series of pages telling you how to specify a main class in a JAR file, seal a JAR file, and perform other tasks that require modifying a JAR file's manifest.

The "Static Import" Construct

Covers the 5.0 feature that lets you refer to static members of other classes without using prefixes. (This can be a dangerous feature, so use it wisely!)

Chained Exceptions

Shows you how to use chained exceptions (a 1.4 feature) to avoid losing exception data when rethrowing an exception.

Thread Pools

Describes how to use this feature, which is part of the concurrency utilities added in 5.0. (Most of the concurrency utilities are for "rocket scientists", but thread pools are more generally useful.)

Generics

The new home of Gilad Bracha's Generics tutorial.

Expect more updates soon. They'll add coverage of other post-1.3 features such as for-each, enums, and so on. Also, Getting Started will cover Mac OS X. And finally, the writers are working on something readers have requested for a long time: a completely new deployment section, which will include information on Java Web Start (for applications) and Java Plug-in (for applets).

To give your feedback to the Tutorial team, use the Feedback Form link that's at the upper right of most pages. Thanks for your support!

This work is licensed under a Creative Commons License.