New Feature: Playlist Center! Pick a topic and let our playlists guide the way.

Easy-to-follow video tutorials help you learn software, creative, and business skills.Become a member

Documenting code with Javadoc

From: Java Essential Training

Video: Documenting code with Javadoc

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.

Documenting code with Javadoc

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.

Show transcript

This video is part of

Image for Java Essential Training
Java Essential Training

71 video lessons · 66704 viewers

David Gassner
Author

 
Expand all | Collapse all
  1. 10m 8s
    1. Welcome
      1m 3s
    2. Is this course for you?
      5m 35s
    3. Using the exercise files
      3m 30s
  2. 31m 24s
    1. The history of Java
      5m 19s
    2. Java compilation and syntax
      8m 54s
    3. Understanding the principles of Java
      8m 28s
    4. Choosing a development environment
      8m 43s
  3. 19m 5s
    1. Installing Java on Windows
      6m 42s
    2. Installing Eclipse on Windows
      3m 19s
    3. Exploring Java on Mac OS X Leopard and Snow Leopard
      2m 27s
    4. Installing Java on Mac OS X Lion
      3m 27s
    5. Installing Eclipse on Mac OS X
      3m 10s
  4. 46m 10s
    1. Creating a Hello World application
      11m 7s
    2. Exploring the Eclipse IDE
      8m 55s
    3. Compiling and running from the command line
      8m 2s
    4. Passing arguments to the application
      8m 17s
    5. Using the Java API documentation
      4m 5s
    6. Memory management and garbage collection
      5m 44s
  5. 58m 57s
    1. Everything is an object
      5m 59s
    2. Declaring and initializing variables
      9m 15s
    3. Working with numbers
      8m 32s
    4. Converting numeric values
      6m 40s
    5. Understanding operators
      7m 58s
    6. Working with character values
      5m 14s
    7. Working with boolean values
      5m 13s
    8. Outputting primitive values as strings
      5m 33s
    9. Creating a simple calculator application
      4m 33s
  6. 53m 40s
    1. Writing conditional code
      5m 35s
    2. Using the switch statement
      8m 50s
    3. Repeating code blocks with loops
      7m 35s
    4. Creating reusable code with methods
      6m 31s
    5. Declaring methods with arguments
      5m 41s
    6. Overloading method names with different signatures
      5m 53s
    7. Passing arguments by reference or by value
      5m 35s
    8. Creating a more complex calculator application
      8m 0s
  7. 20m 30s
    1. Using the String class
      5m 44s
    2. Building strings with StringBuilder
      3m 34s
    3. Parsing string values
      3m 19s
    4. Working with date values
      7m 53s
  8. 20m 44s
    1. Understanding compile-time vs. runtime errors
      4m 5s
    2. Handling exceptions with try/catch
      4m 55s
    3. Throwing exceptions in methods
      2m 50s
    4. Using the debugger
      8m 54s
  9. 32m 22s
    1. Using simple arrays
      4m 47s
    2. Using two-dimensional arrays
      6m 17s
    3. Managing resizable arrays with ArrayList
      7m 14s
    4. Managing unordered data with HashMap
      6m 5s
    5. Looping through collections with iterators
      7m 59s
  10. 52m 2s
    1. Understanding encapsulation
      5m 59s
    2. Creating and instantiating custom classes
      8m 8s
    3. Organizing classes with packages
      6m 47s
    4. Creating and using instance methods
      6m 52s
    5. Storing data in instance variables
      6m 56s
    6. Using constructor methods
      5m 40s
    7. Managing instance data with getter and setter methods
      8m 26s
    8. Using class variables and Enum classes
      3m 14s
  11. 41m 15s
    1. Understanding inheritance and polymorphism
      9m 12s
    2. Extending custom classes
      9m 1s
    3. Overriding superclass methods
      3m 8s
    4. Casting subclass objects
      5m 3s
    5. Understanding interfaces and implementing classes
      4m 2s
    6. Creating your own interfaces
      4m 14s
    7. Using abstract classes and methods
      6m 35s
  12. 32m 17s
    1. Managing files with the core class library
      7m 46s
    2. Managing files with Apache Commons FileUtils
      7m 32s
    3. Reading a text file from a networked resource
      7m 52s
    4. Parsing an XML file with DOM
      9m 7s
  13. 17m 39s
    1. Creating your own JAR files
      4m 54s
    2. Understanding the classpath
      5m 2s
    3. Documenting code with Javadoc
      7m 43s
  14. 47s
    1. Goodbye
      47s

Start learning today

Get unlimited access to all courses for just $25/month.

Become a member
Sometimes @lynda teaches me how to use a program and sometimes Lynda.com changes my life forever. @JosefShutter
@lynda lynda.com is an absolute life saver when it comes to learning todays software. Definitely recommend it! #higherlearning @Michael_Caraway
@lynda The best thing online! Your database of courses is great! To the mark and very helpful. Thanks! @ru22more
Got to create something yesterday I never thought I could do. #thanks @lynda @Ngventurella
I really do love @lynda as a learning platform. Never stop learning and developing, it’s probably our greatest gift as a species! @soundslikedavid
@lynda just subscribed to lynda.com all I can say its brilliant join now trust me @ButchSamurai
@lynda is an awesome resource. The membership is priceless if you take advantage of it. @diabetic_techie
One of the best decision I made this year. Buy a 1yr subscription to @lynda @cybercaptive
guys lynda.com (@lynda) is the best. So far I’ve learned Java, principles of OO programming, and now learning about MS project @lucasmitchell
Signed back up to @lynda dot com. I’ve missed it!! Proper geeking out right now! #timetolearn #geek @JayGodbold

Are you sure you want to delete this note?

No

Thanks for signing up.

We’ll send you a confirmation email shortly.


Sign up and receive emails about lynda.com and our online training library:

Here’s our privacy policy with more details about how we handle your information.

Keep up with news, tips, and latest courses with emails from lynda.com.

Sign up and receive emails about lynda.com and our online training library:

Here’s our privacy policy with more details about how we handle your information.

   
submit Lightbox submit clicked
Terms and conditions of use

We've updated our terms and conditions (now called terms of service).Go
Review and accept our updated terms of service.