Object-Oriented Enterprise Application Development

1
Object-Oriented Enterprise Application Development

• Javadoc
• Last Updated 06/30/2001

2
Topics

• This Javadoc overview examines
• Purpose
• Javadoc tags
• Generating javadoc

3
Javadoc Comments
4
Purpose

• Javadoc is one of the tools that makes up Java.
• It's used to provide documentation at the point
  that it's most likely to be maintained the
  source code.

5
Structure

• Javadoc is generated using a two (2) step
  process
• Place the appropriate comments and tags within
  your Java source code
• Execute the javadoc utility.

6
Comments

• /
• All javadoc comments begin with a variation of
• the multi-line edit. The only difference is
• that it has two asterisks instead of just one.
• These comments will be ignored by the java
• compiler, but will be used by javadoc to
• generate the appropriate HTML documents.
• /

7
Tags

• While there are a variety of javadoc tags, there
  are only a few that we commonly use
• _at_author
• _at_version
• _at_param
• _at_return
• _at_throws

8
Sample(1 of 2)

• package sample
• /
• This class is used to illustrate the basic
  concepts of
• javadoc. If this were "real" javadoc, then
  this text would
• go into some detail about what exactly this
  class was for
• and how another developer would use it.
• _at_author Chris Jones
• _at_version 1.0
• /
• public class Sample

9
Sample(1 of 2)

• /
• The javadoc should provide details about
  what this method
• does really, including any preconditions,
  postconditions,
• and other information another developer
  might need.
• _at_param arg1 Describe what the argument is
  for, any
• limitations on its value, etc. You'll have
  one of these
• tags for each parameter passed to the
  method.
• _at_return Describe what the return value
  represents.
• _at_exception Describe each exception thrown by
  the method.
• You'll have one of these tags for each type
  of exception
• identified by the method's throw clause.
• /
• public int doStuff(int arg1)
• throws Exception
• // TODO whatever needs doing....

10
Tags

• Obviously you might not need all of the tags for
  each method within the class.
• For example, if the method doesn't throw an
  exception, then you wouldn't use an _at_exception
  tag.
• Use only those tags that make sense.

11
Javadoc Generation
12
Utility

• Once the javadoc has been written into your code,
  you can generate the associated HTML using the
  javadoc utility.
• Javadoc, like java, javac, and jar, is located in
  your ltJAVA_HOMEgt\bin directory.
• This utility works best when your source code is
  placed into directory structures that mirror your
  packages.

13
Utility(2 of 2)

• Javadoc has many optional arguments. To see them
  and experiment, just type javadocfrom the
  command line
• It isn't necessary to have compiled the .java
  files before using javadoc.

14
Utility(2 of 3)

• For this class, most of the default settings are
  fine javadoc d ltoutput-dirgt ltpackage
  listgtFor examplejavadoc d javadoc sample