Page 1 – Autumn 2009Steffen Vissing Andersen SDJ I1, Autumn 2009 Agenda: Java API Documentation Code Documenting (in javadoc format) Debugging

Page 1 – Autumn 2009 Steffen Vissing Andersen

SDJ I1, Autumn 2009

Agenda:

• Java API Documentation• Code Documenting (in javadoc format)

• Debugging


Online Help


Help (documentation for classes and methods)

Purpose:

Want to see documentation for the class String


Help (SHIFT + F1)

SHIFT + F1 Click on String

Open the javadoc help:

Rightclick "Open in Help Contents"


Javadoc-Help (for class String)

This workspace is setup to get online help

Note: Following the video about Eclipse workspace on "HowToInstall SDJSoftware" (Tools menu in the SDJ folder)The help will be local instead of online


Javadoc-Help for String (Method summary)


Javadoc-Help for String (Method details)


Documenting the code – javadoc

• Your own classes should be documented the same way library classes are

• Other people should be able to use your class without reading the implementation

• Make your class a 'library class'!


javadoc for a class

• Documentation for a class should include:• the class name• a comment describing the overall purpose and

characteristics of the class• a version number• the authors’ names• documentation for each constructor and each method


Javadoc for a method

• The documentation for each constructor and methods should include:• the name of the method• the return type• the parameter names and types• a description of the purpose and function of the

method• a description of each parameter• a description of the value returned


javadoc comments

/** * A Student class representing a student * @author Steffen Vissing Andersen * @version 1.0, 30/11/2008, 12.55.08 */public class Student extends Person{ private int studentNumber; /** * Three-argument constructor * @param address the address * @param name the name * @param number the student number */ public Student(String address, String name, int number) { super(address, name); this.studentNumber = studentNumber; }


javadoc comments

/** * @return the studentNumber */ public int getStudentNumber() { return studentNumber; }

/** * @param studentNumber the student number to set */ public void setStudentNumber(int studentNumber) { this.studentNumber = studentNumber; } }


javadoc comments


javadoc comments


Some javadoc comments

• Between /** and */ is a javadoc comment and will not be part of your program

• javadoc comments uses a number of tags, like:@author The name of the programmer@version The version of the class@param Description of parameters for a method@return Description of what is returned from a

method@throws Description of the exceptions thrown by the

method@see A reference to something else

• Find more tags in the documentation• The javadoc comments will be extracted of the

javadoc tool


How to generate javadoc files

1. Write your javadoc comments in the code

2. Generate javadoc files from the Project menu in Eclipse• Use javadoc.exe file• Select project or files• This is the location of

the javadoc files• the startup file is called

index.html


Debugging

• Debugging can be performed• Using the build-in Debugger in Eclipse• Inserting print statements before and after statements

that we want to inspect


The build-in Debugger

2. step:Debug:SHIFT + F11(or Run menu)

Note: You may answer yes in a confirm box

1.step:Insert "Break points": doubbleclick...


Debugging our solution

You are here in the code:

The Debug Perspective opens

The variables



You can 1) step into2) step over

Next statementIf this is from the API then step over. If it is a method or something you want to inspect then step into



Next statementThis is from the API then step over

step over



Next statementThis is our own work (here the constructor), and we want to inspect thisstep intostep into


Code Documentation (API documentation)

You have to present a subject to the class. Subject: Java API Documentation.

• Why use online help?• How can you get an overview of the lots and lots of classes and

methods in the API?• How can you see which methods are available for a specific class in

the API?• How can you access the details of a class and a method from the API?• Take at least one example of a class in the API and explain what you

can see in the API documentation• Explain why it is a good idea to use the API documentation• Show how you think the praxis of using the API documentation should

be incorporated in your use of Java and Eclipse – and how you think your fellow student should use the API documentation


Code Documentation (javadoc)

You have to present a subject to the class. Subject: Code Documentation in javadoc

• Why should you use javadoc for your code documentation?• How can you generate a javadoc Documentation for your programs? • How should you make comments in the source code?• Explain why it is a good idea to use the API documentation• Show how you think the praxis of making code documentation should

be – and how you think your fellow student should make this (as easy as possible)


Debugging

You have to present a subject to the class. Subject: Debugging by hand, by use of print statements and using the build-in debugger in Eclipse

• Why should you debug some of your programs?• What can you do if your code turn out not to do what it should do?• How can you look for logical errors (bugs)?• How can you debug a code snippet by hand? • How can you debug a code snippet using print statements?• Explain why it is a good idea to have some kind of strategy to look for

bugs • Show how to use the build-in debugger in Eclipse• Where should you insert break points?• Show how you think the praxis of identifying bugs could be – and how

you think your fellow student should do this (as easy as possible)

Documents

Page 1 – Autumn 2009Steffen Vissing Andersen SDJ I1, Autumn 2009 Agenda: Java API Documentation Code Documenting (in javadoc format) Debugging