Register Login





|

Top Links: >> 80. Technology >> Internet Technology Summit Program >> 1. Java Introduction
Current Topic: 1.2.8.Javadoc to generate documentation
Sub-Topics: 1.2.8.1. Managing Terminal window on Mac (Apple) while creating Javadoc
-- Scroll to check for more content below...
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).

The sample below presents the most common case.

- % javadoc -d \home\html -sourcepath \home\src -subpackages java -exclude java.net: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:
Was it clear so far? Highlight the text in question Or


javadoc -d C:\espace\week1\html -sourcepath C:\espace\week1\src day5

The only dofference for you is that your workspace is ITS.
So, your command line should look like:

javadoc -d C:\ITS\week1\html -sourcepath C:\ITS\week1\src day5

1.2.8.Javadoc

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.

1.2.8.JavadocInWindowsCommand

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.

1.2.8.JavadocInEclipse

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.

Questions and Answers (QnA): QnA1 | QnA2 | QnA3 | QnA4 | QnA5 | QnA6 | QnA7
We offer a fun way to share your experience and be rewarded.
You create a puzzle - quiz with a good question and several answers, one correct and several wrong ones.
The question as well as answers can include text, links, video.
This is your creation, completely up to your taste, humor, and of course your knowledge.
If there is an existing quiz above, you need first to solve the puzzles and evaluate the quality (at the bottom of every quiz).
After finishing the existing quiz you will be able to create your own. The best puzzles will be rewarded!
We invite you to create your own questions and answers (QnA) to increase your rank and win the Top Creativity Prize!

Topic Graph | Check Your Progress | Propose QnA | Have a question or comments for open discussion?

Have a suggestion? - shoot an email
Looking for something special? - Talk to AI
Read: IT of the future: AI and Semantic Cloud Architecture | Fixing Education
Do you want to move from theory to practice and become a magician? Learn and work with us at Internet Technology University (ITU) - JavaSchool.com.

Technology that we offer and How this works: English | Spanish | Russian | French

Internet Technology University | JavaSchool.com | Copyrights © Since 1997 | All Rights Reserved
Patents: US10956676, US7032006, US7774751, US7966093, US8051026, US8863234
Including conversational semantic decision support systems (CSDS) and bringing us closer to The message from 2040
Privacy Policy