From the course: Java 8 Essential Training

Documenting code with Javadoc - Java Tutorial

From the course: Java 8 Essential Training

Start my 1-month free trial

Documenting code with Javadoc

“

- 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. It's just as fast as I showed you here on screen. Now, notice, up at the top, I'm getting a message in Internet Explorer, JavaScript is disabled on your browser. You can turn that restriction off, or, as I prefer to do, you can actually open the files in another browser that doesn't have that restriction. I'll come back to IntelliJ IDEA, then I'll right-click on the project, and choose Show in Explorer, or, if you're working on Mac, Show on Finder. Then, I'll double-click into my project and then into my docs folder. And here are all the files that have been generated. The starting file is the index file. Now, these next steps will differ depending on your operating system. But on Windows, with Chrome installed, I can right-click and choose Open with Google Chrome. And when they open in Google Chrome, you don't have the JavaScript restrictions. Here's what the documentation looks like. In the top left corner, there's a list of Packages. 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.

Contents