javadoc course
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
|