Easy-to-follow video tutorials help you learn software, creative, and business skills.Become a member
Java docs are files that you can generate out of your source code to document your code, because a well-designed Java application can contain dozens, hundreds or even thousands of Java classes, documentation is critical for long-term maintenance. As you code, it's a good idea to add comments to your code to describe how the classes are designed to work. Then later on you will be able to look at the documentation and figure out how the application was architected. The first step to generating Java docs is to add what are known as element comments into your code.
An element comment is a comment that applies to a particular element of the code, such as a class, a method, a field and so on. Here's how you add an element comment. I'm working in a version of the project called Java docs and I'm in the Main class, I'll double-click the name of the class and then I'll go to the menu and choose source, generate element comment. Notice that there's a keyboard shortcut available for this. By default, Eclipse adds an annotation my name as the author. An element comment is like a block comment, it starts with a / and then *, but then it adds another * on the first line, that double asterisks is the indicator that this is an element comment that should be used by the Java Doc system.
You can add other annotations to your element comments. I'll place the cursor on the next line and type in @ character and I'll get a list of the known annotations, and I'll choose version, and I'll set it to 1.0. You can also add your own comments. These typically go before the annotations. I'll place the cursor on the first line of the comment and press Enter or Return and I'll say This is the main class for my app. I'll Save that change and scroll down a little bit and show you that all of this class has a main method and I'll decide, I don't need to comment anymore of this, but I do want to add comments to some of my other code.
So I'll go to the Olive class. I'll double-click the class name and choose Source, Generate element comment, I'll decide I don't need to put in my author information, I already have that in the Main class, but I will add a comment, This is a superclass for all olives. You can also add element comments for fields and methods, I'll double-click BLACK and choose Source, Generate element comment, and say This is for black olives and I'll double-click GREEN and generate the comment and say This is for green olives.
I'll scroll down and select the crush method and add a comment for that and say call this to crush a single olive. Finally, I'll go to the kalamata.java file, and I'll comment this particular method which was only implemented on this particular class. I'll select the method name, add a comment, and I'll add This method is unique to kalamata olives.
Now I'm ready to generate my Java docs. I'll make sure I saved all of my changes and I'll go to the menu and choose File, Export. In the Export dialog I'll select Java and then Java Doc and click Next, in this screen I'm asked what the Java.command is? If this value is blank, click the configure button and navigate your JDK installation folder, and then to the bin folder, and the java.command. Next, indicate what types you are going to generate Java docs for? I'd recommend selecting the entire application; this will make sure that you're generating Java docs for all packages and all classes.
You can also be specific about which access modifiers you're creating Java docs for. I'd recommend the default of public. Next, Browse and indicate where you want to generate your docs. I've selected a new folder named doc under my project folder that value may appear by default on your system, but if it doesn't, browse and select it. Now I'll click Next, and here I'm asked if I want to include referenced archives and projects, I'll leave these all unselected. If you were to select any of these, you would also get Java docs for classes in the core Java class library, and you probably don't want to do that.
You can also set an explicit document title and indicate which of these tags you want to document. I'll click Finish and it will take just a few moments to generate the Java docs. I'll close the window and here's my new doc folder in my project folder, if you don't see it there, try refreshing, right-click on the project and choose Refresh. I'll open the doc folder and I'll see a whole bunch of files that have been generated. The beginning file is named index. html working in Eclipse you can just double-click it, and it will open in a browser view.
I'll double-click the tab of the browser view to expand it to full screen and here's all my documentation. I'll click into the olivepress package and see my main class and here's my comment "This is the main class for my app." Here is my version and here is the author information. Now, I'll go to the olives package over here and I'll click into the olive class and I'll see the comment, This is a superclass for all olives, and I'll also see the comments for my black and green static long fields.
And finally I'll go to Kalamata, where I added the comment for the custom method. I'll scroll down to get origin, and there is my comment. Now, because this is being generated in HTML, you can use a certain small set of HTML tags to mark up your comments. I'll close the browser view and I'll go back to Kalamata, and I'll place the cursor before Kalamata and I'll add a beginning b tag, and then after Kalamata, I'll add a closing tag.
I'll Save and then I regenerate the Java docs, I'll go to File, Export, Java Doc, Next, I'll make sure that I selected the entire Java docs application again, and then I'll click Finish and that will overwrite the existing files. I'll go back to my Doc folder, I'll open index.html, I'll go to Kalamata and scroll down, and there is the result. The word, Kalamata is bolded.
So the last thing I'll show you is that in Eclipse there's a Java docs tab which will show you Java docs information for classes in your application. When you're working with classes from the Java class library, all you need to do is place the cursor in the name of the class and then look in the java.tab, and if everything is configured correctly, which it should be by default, you should see simple Java docs displayed there, but once you've generated your own Java docs, this will work for your application as well. I'll go to the Kalamata.java file and I'll click onto the getOrigin method and I'll see the Java doc comment that I just generated, this method is unique to Kalamata olives.
It's a good idea as a Java programmer to get used to adding element comments as you create new methods, fields, and classes. That will then ensure that when you're ready to generate the Java docs, you don't need to go back and add all that documentation later on, that's a tough thing to do. If you do it in small pieces as you code, and as the purpose of the elements is fresh in your mind, it'll result in well-documented and well maintainable applications.
Get unlimited access to all courses for just $25/month.Become a member
61 Video lessons · 96931 Viewers
56 Video lessons · 110616 Viewers
71 Video lessons · 79438 Viewers
131 Video lessons · 38120 Viewers
Access exercise files from a button right under the course name.
Search within course videos and transcripts, and jump right to the results.
Remove icons showing you already watched videos if you want to start over.
Make the video wide, narrow, full-screen, or pop the player out of the page into its own window.
Click on text in the transcript to jump to that spot in the video. As the video plays, the relevant spot in the transcript will be highlighted.