Instructor

John E. Darrow [ resumé | main page ]

About javadoc

"javadoc" is a program that scans Java source code looking for: class members and for javadoc-style comments above such members.

javadoc generates documentation that lists those members, using the javadoc-style comments as the descriptions of those members. This "API documentation" is in a form suitable for a programming audience. The quality and readability of such documentation depends on the quality and readability of the javadoc-style comments in the source code.

Special symbols can be added to javadoc-style comments to affect the output. For example, the @see tag results in a "See also" section in the documentation, complete with links to the other documentation.

Course Description

The debate continues in many companies regarding creating API documentation for their software: "Should we go with javadoc and its HTML output or with FrameMaker and its PDF/HTML output?" And a related question: "If we can get decent-looking documentation by running javadoc against our source code, why not just have the developers write the comments and not involve tech writers at all?" It may be that one or both sides are limiting their thinking to the simple options of authoring in javadoc versus authoring in FrameMaker.

What makes this more than just another course about javadoc tags?

• It brings up options and issues about the writing process and the place of javadoc and FrameMaker that the participant might not have considered so that the participant can help his or her company make the right decisions.
• It reviews the benefits of a custom javadoc doclet.
• It presents the basic tags and command line switches of javadoc.
• It highlights details not covered or not covered clearly in Sun's web pages about javadoc.
• It advises participants on writing style, presents an excellent editing tool (not vi!), and advises on the setup of a Tech Pubs directory structure in preparation for team API documentation development (both reference and concept documentation).
• It presents workarounds and tricks in the use of javadoc and the altering of its output.
• It is relevant and practical.

What this seminar does NOT cover

• how to program in Java
• how to recognize class members in Java source code
• the fundamental concepts of creating API documentation

Objectives

Upon completion of this course, the participant will be able to:

• identify the pros and cons of choosing javadoc, FrameMaker or both for API reference documentation
• demonstrate understanding of the most-used javadoc tags and command line switches
• pinpoint where the API reference writer's effort is best used
• recommend to his or her company how best to use javadoc and prepare for its use
• write comments in a style appropriate for API reference documentation and for javadoc
• identify the potential benefits and savings to a company from using a custom doclet

Intended Audience

This course is ideal for:

• writers, developers, and their managers who are weighing due dates against possible authoring and output formats and who need to advise their companies of the best approach for API documentation
• writers, developers, and managers wanting to know how to write for and use javadoc

Recommendation: invite at least one member from both Tech Pubs and Development so that both teams understand and can discuss the issues more effectively.

Course Outline

Overview:

• The API reference writer’s task, in a nutshell
• What javadoc does
• Deficiencies of the javadoc output format
• javadoc vs. FrameMaker: which is best for you?
• The benefits of a custom doclet

Writing for javadoc:

• Writing style for API comments
• Comment format for javadoc
• Definitions: documented, referenced, external
• javadoc tags
• Potential source files for javadoc

Using javadoc:

• Command line switches for all doclets
• Additional switches for the standard doclet
• Preparing to use javadoc
• Exercises

Duration

Three hours.

Prerequisites

A basic understanding of these concepts of Java API documentation:

• Classes and interfaces are in packages and have members (constructors, methods, fields and nested classes, where constructors and methods can have parameters).
• Such entities need to be explained in terms appropriate for a developer audience and presented in a logical and effective format.

Those who meet the prerequisites are most likely to benefit most from this course. However, those who do not meet the prerequisites are still welcome to attend,with an understanding that the prerequisite concepts will not be reviewed.

Managers, for example, can benefit from learning about the basic concepts, issues and requirements of javadoc, information which may help them decide whether additional training in Java API documentation is appropriate for their teams.

Methods

Interactive lecture: 90%
Exercise: 10%

Computers are not required for the students. Those who bring computers can conduct the exercises, though their computers will need to be prepared in advance as described below.

Fee

$450 per class, or $150 per attendee, whichever is greater.

Class size

40 students maximum.

Room and computer requirements

Room requirements:

• A whiteboard.
• A computer with projector for the instructor.
• Optional: computers for students for exercise period.

Computer requirements:

• Java 2 SDK and TextPad (see instructions here).
• jdsamp.zip: downloaded from here and unzipped into a directory named "code" for use in the course.

  John E. Darrow 
  Other John Links