Join David Gassner for an in-depth discussion in this video Documenting code with Javadoc, part of Java 7 Essential Training.
- The Java Development Kit includes the tool named Javadoc. Javadoc's job is to extract documentation about your Java application, including information directly drawn from the code, but also from comments that you can put into your code. I'll demonstrate this in this project, named Javadoc. In order to create a Javadoc comment, place the cursor before a class declaration, a method, or a variable declaration. Then, add a comment.
A Javadoc comment starts with a slash and two asterisks, and you can create it easily by typing those characters, slash, asterisk, asterisk, and then pressing enter or return. And the cursor will land right there, and you can start typing. So, for example, in this position, I might write a whole bunch of information about my application. Along the way, you can include a certain amount of HTML markup. So, for example, I'm going to wrap the words olive press with bold tags, and then I'll also wrap the words press olives, so that they're emphasized.
If you add a Javadoc comment above a method, IntelliJ IDEA automatically adds a param tag and populates it with the name of the argument, but then it's up to you to add any additional explanation. I'll just add the text, The main method, and then, next to args, I'll add an array of String values. Now, I'll generate the docs for the first time. The docs will be placed in whatever folder you like. I'm going to go to my project, notice I'm in the Project view, and I'll right-click and create a new directory.
And I'll name it docs. Then, I'll go to the menu and choose Tools, Generate Javadoc. For the Output directory, I'll browse and select the folder I just created. I'll type Desktop to get to my desktop, and then I'll drill down to my Exercise File folder, that's under Chapter 12, 12_01, Javadoc. And I'll choose the Docs sub-folder. The Output directory slider lets you choose what level of visibility you wanna include in your documentation.
By default, it's set to protected, so only public and protected classes would be included. But if you want to include nested classes, you would drag this up to the top to private. You can also select certain tags. For example, I'll say that I want to include the author and the version tag. You can also set the Locale and add Other command line arguments, and control the amount of memory that's available to the Javadoc Tool. Then, I'll click OK, and after a few moments, my documentation is generated.
My application has two packages, the base package and the model sub-package. And as you click on the packages, you'll see a list of the Classes, Enumerations, Interfaces, and other files that you've created in those Packages. You can click into any Class to see the documentation about that Class. This is an example of a Class where the docs have been generated purely from the code. I didn't add any special comments. And notice that the Javadoc tool has figured out that Kalamata and Ligurian are sub-classes of the current Class.
I can easily click those Classes and jump to their documentation. I'll go back to the base package and choose my Main class. And this is where I see the comments that I added. Here's the comment for This is an olive press application. And you can see the effect of the HTML tags that I added. And here's the comment for the main method. I'll scroll to the bottom of the page, to the Method Detail section, and here's the additional comment that I added about the args parameter.
If you decide to use the Javadoc tool, you can go through your entire application and add Javadoc comments to your Classes, Methods, Arguments, and any other members that you think need a bit of explanation. For applications that you want to keep around for a long time, that will need to be maintained, then Javadoc Tool is absolutely critical to help you understand later what you are programming today.
- Understanding the history and principles of Java
- Installing Java, IntelliJ IDEA, and BlueJ
- Creating a Java project
- Working with variables, values, and expressions
- Working with object data types
- Building, comparing, and parsing strings
- Debugging and exception handling
- Creating loops and reusable code
- Passing arguments by reference or value
- Using simple and complex arrays
- Creating custom classes
- Understanding inheritance and polymorphism
- Managing files with Java libraries
- Documenting code with Javadoc
- Packaging classes in JAR files