You have a privilege to create a quiz (QnA) related to this subject and obtain creativity score...
1.2.8.Javadoc to generate documentation You can run javadoc on entire packages or individual source files. Each package name has a corresponding directory name. In the following examples, the source files are located at C:\home\src\java\awt\*java. The suggested destination directory is C:\home\html.
Documenting One or More Packages
To document a package, the source files (*.java) for that package must be located in a directory having the same name as the package. If a package name is made up of several identifiers (separated by dots, such as java.awt.color), each subsequent identifier must correspond to a deeper subdirectory (such as java/awt/color). You may split the source files for a single package among two such directory trees located at different places, as long as -sourcepath points to them both - for example src1\java\awt\color and src2\java\awt\color.
You can run javadoc either by changing directories (with the cd command) or by using -sourcepath option.
The option -d defines destination directory where the javadoc will create html documentation files.
The option -sourcepath defines a directory where java source is located.
The examples below illustrate both alternatives.
- Case 1 - Run recursively starting from one or more packages - This example uses -sourcepath so javadoc can be run from any directory and -subpackages (a new 1.4 option) for recursion. It traverses the subpackages of the java directory excluding packages rooted at java.net and java.lang. Notice this excludes java.lang.ref, a subpackage of java.lang).
To also traverse down other package trees, append their names to the -subpackages argument, such as java:javax:org.xml.sax.
- Case 2 - Run on explicit packages after changing to the "root" source directory - Change to the parent directory of the fully-qualified package. Then run javadoc, supplying names of one or more packages you want to document:
- C:> cd C:\home\src\
- C:> javadoc -d C:\home\html java.awt java.awt.event
- Case 3 - Run from any directory on explicit packages in a single directory tree - In this case, it doesn't matter what the current directory is. Run javadoc supplying -sourcepath with the parent directory of the top-level package, and supplying names of one or more packages (the sample below will produce Javadoc for two packages: java.awt and java.awt.event) you want to document:
- C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt java.awt.event
- Case 4 - Run from any directory on explicit packages in multiple directory trees - This is the same as case 3, but for packages in separate directory trees. Run javadoc supplying -sourcepath with the path to each tree's root (colon-separated) and supply names of one or more packages you want to document. All source files for a given package do not need to be located under a single root directory - they just need to be found somewhere along the sourcepath.
In the case when your workspace is in c:/ITS - directory and your source is in the week1 project, to generate documentation for your package day5 use the following command:
C:> javadoc -d C:\ITS\week1\html -sourcepath C:\ITS\week1\src day5
Find HTML files in the provided destination: c:\ITS\week1\html. In Eclipse refresh the project to see this new directory and the files.
- Case 5 - In the Eclipse - Maven environment -
The source is usually under {projectLocation}/src/main/java - directory.
The recommended place for javadoc would be {projectLocation}/src/main/webapp/javadoc - directory.
For example, a project location is c:\allProjects\myProject; desired source packages are: com.its.util and com.its.ds.
C:> javadoc -d c:\allProjects\myProject\src\main\webapp\javadoc -sourcepath c:\allProjects\myProject\src\main\java com.its.util com.its.ds
Assignments: 1. Generate documentation for all packages created in the week1 project.
2. Use a browser to browse the documentation.
3. Create 4 QnA on the subject and email to dean@ituniversity.us
Reference: http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html
The screen shot below illustrates creating Javadoc files in the workspace espace.
Take a look at the command line below:
Here is another illustration of creating Javadoc with MS Windows Command (CMD).
1. Change directory to see the main package of your sources.
I recommend you to use the cd command and then immediately the dir command to list the files in the directory.
For example: cd .. This is getting one directory above. If you were in the c:/ITS/week1 - directory, now you are in c:/ITS - directory.
Or
cd week1 dir Now you are back to the c:/ITS/week1 - directory and with the dir - command you will see all directories and files inside that directory.
In another example, the directory is c:/espace/BASE/src/main/java
This is the place where the main source package "com" is located.
The full name of the package is "com.its.util".
We would like to provide Javadoc for the sources under that package name.
Let us assign the directory for resulting Javadoc html files as -d c:/aws/html
Enter:
javadoc -d c:/aws/html com.its.util
Then you will see Javadoc generation messages and find the file index.html in the c:/aws/html - directory.
Using Eclipse to generate Javadoc files
Eclipse has its own options to generate Javadoc. Follow the steps 1-5 below.
Just remember that no matter which tools are used the core for the documentation must be provided by a developer with meaningful comments created with Javadoc style in Java sources.
Possible errors in Eclipse: After you highlighted the project and in the main menu at the top selected Project - Generate Javadoc... click NEXT (instead of FINISH), then NEXT again and check carefully JRE Source Compatibility - version. It must match your compiler version. Otherwise Javadoc will throw ERROR messages.
