Lecture 7

Javadoc

• an automated tool for documentation and generation of your java code
• operates through the comments in your java code

Remember: Java Comments

//... -> is a single line comment

/* ... */ -> is a multiline comment

/** ... */ -> format used for Javadoc documentation

Note: for this documentation '...' refers to details you filled in.

• document every public entity in your code
• place the /** ... */ comments (Javadoc comments) immediately prior to each public entry
• Entries that should have Javadoc comments:
  
• the class itself
• the constructors (public)
  
• the methods (public)
• any public fields
• any non-Javadoc comments will be ignored by Javadoc. So you can still comment your code as necessary

Example

/** this class contains a BankAccount balance and provides methods for manipulating that balance */

public class BankAccount {

/** this is the default constructor which sets the balance to zero */

public BankAccount(){balance=0;}


//info goes here

private double balance;
//no Javadoc comments here, because this is not part of the public
//even if Javadoc sees Javadoc comments here it will avoid when rendering itself

• Javadoc has special keywords used within a Javadoc comment to document parameters and return values
• @param - parameters
  
• @return - return values
  

Example

/** Add a deposit to the current balance
@param amount amount of the deposit
*/

public void deposit(double amount){
balance = balance + amount
}


Example 2

/** returns the current balance
@return The value of the current balance
*/

public double getbalance(){return balance;}

//double is a 'non void' return value


Console:

$javadoc BankAccount.java

• if you have more than one java file in the folder you wish to create a Javadoc for

$javadoc *.java

• this creates many different files that will be included in the Javadoc file. to access the file in a webbrowser open index.html

Javadoc Practices

• Javadoc documents the public interface of your code (everything w/ the public tag)
• it's up to you to provide descriptions. Be as detailed as reasonable
• good practice to produce Javadoc at the same time as the public interface
• Always Document your Code!!!