Project Analysis and Design - SCJD Exam with J2SE 5 - page 44

The -link and the -linkoffline options enable you to link to other preexisting APIs. For
example, if you used the String class as a parameter in one of your methods, you might like to
have your API documentation for your method include a hyperlink back to Sun's API docu-
mentation for the String method.
You would normally use the -link option whenever you do not have a copy of the pre-
existing API local to you, but you can access it over the Web.
The -linkoffline option is preferred when you have a local copy of the preexisting API
documentation, or when you have a local copy of the package-list file from the preexisting
API documentation, or when you cannot access the preexisting API over the Web.

■ Tip Whenever possible you should refer to local documentation rather than looking at it over the Web,

simply because it will be faster for you. Likewise, linking “offline” by using your local copy of the documen-
tation will be faster than accessing the required file over the Web.

Obviously, you would not want to type such a complex command line every time you
wanted to regenerate your API documentation. One way of working around this is to put all
the options (one per line) into a plain text file, and then refer to that file on the command line.
For example, if you had put all the options in a file named javadoc.options , you could use the
following command line to generate your API documentation:

javadoc @javadoc.options sampleproject.gui sampleproject.db sampleproject.remote

Working with Packages
If you were to put all the files on your computer into one folder, this one folder would quickly
become unmanageable, and finding any particular file would be a nightmare. To avoid this,
you probably organize folders to store related files—one for accounting information, another
for job hunting, another for music, and so on. Some of these folders may have subfolders to
provide further subcategories.
Developing software has the same potential issue. Fortunately, Sun has provided us with a
platform-independent equivalent of the folders: packages. You can locate classes belonging to
a specific package by the fully qualified package and class name, even if the operating system
has no concept of folders, directories, or a hierarchical file system.
When starting any project, consider what logical modules or functionalities your project
might have, and place the classes related to that functionality into its own package. In the case
of our project, we will have a set of classes that provide the graphical user interface, another
set of classes that provide network functionality, and another set of classes that provide data
access functions. We could therefore start with the following potential packages:

gui
network
database