Friday, January 19, 2007

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!!!

4 comments:

Niv said...

Good notes, thanks!
I think I'll print yours, since mine are a bit messy (bad handwriting)

Also, if anyone wants to join, there's a Computer Science@York facebook.com group.

P.S. If anyone plans on doing group study before the midterm etc..., add me in facebook (Niv Majar) and leave a message - a study group would be really nice for this course

Jake deVos said...

hey,
i don't have facebook, and i kinda refuse to get it lol.. the blog works well for me BUT a study group is an awesome idea.. before next test lets arrange something!!! we can all meet @ scott and study or somethin

nauman said...

that would be cool

Domenico said...

I really like your ideas guys. I'm in for it, I should be well enough to come back in on Monday so I'm good to go on any practice together.

And Niv, I'll go join that group and add you within the next 24 hours.