Page 1 – Autumn 2009 Steffen Vissing Andersen
SDJ I1, Autumn 2009
Agenda:
• Java API Documentation• Code Documenting (in javadoc format)
• Debugging
Page 2 – Autumn 2009 Steffen Vissing Andersen
Online Help
Page 3 – Autumn 2009 Steffen Vissing Andersen
Help (documentation for classes and methods)
Purpose:
Want to see documentation for the class String
Page 4 – Autumn 2009 Steffen Vissing Andersen
Help (SHIFT + F1)
SHIFT + F1 Click on String
Open the javadoc help:
Rightclick "Open in Help Contents"
Page 5 – Autumn 2009 Steffen Vissing Andersen
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
Page 6 – Autumn 2009 Steffen Vissing Andersen
Javadoc-Help for String (Method summary)
Page 7 – Autumn 2009 Steffen Vissing Andersen
Javadoc-Help for String (Method details)
Page 8 – Autumn 2009 Steffen Vissing Andersen
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'!
Page 9 – Autumn 2009 Steffen Vissing Andersen
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
Page 10 – Autumn 2009 Steffen Vissing Andersen
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
Page 11 – Autumn 2009 Steffen Vissing Andersen
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; }
Page 12 – Autumn 2009 Steffen Vissing Andersen
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; } }
Page 13 – Autumn 2009 Steffen Vissing Andersen
javadoc comments
Page 14 – Autumn 2009 Steffen Vissing Andersen
javadoc comments
Page 15 – Autumn 2009 Steffen Vissing Andersen
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
Page 16 – Autumn 2009 Steffen Vissing Andersen
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
Page 17 – Autumn 2009 Steffen Vissing Andersen
Debugging
• Debugging can be performed• Using the build-in Debugger in Eclipse• Inserting print statements before and after statements
that we want to inspect
Page 18 – Autumn 2009 Steffen Vissing Andersen
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...
Page 19 – Autumn 2009 Steffen Vissing Andersen
Debugging our solution
You are here in the code:
The Debug Perspective opens
The variables
Page 20 – Autumn 2009 Steffen Vissing Andersen
Debugging our solution
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
Page 21 – Autumn 2009 Steffen Vissing Andersen
Debugging our solution
Next statementThis is from the API then step over
step over
Page 22 – Autumn 2009 Steffen Vissing Andersen
Debugging our solution
Next statementThis is our own work (here the constructor), and we want to inspect thisstep intostep into
Page 23 – Autumn 2009 Steffen Vissing Andersen
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
Page 24 – Autumn 2009 Steffen Vissing Andersen
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)
Page 25 – Autumn 2009 Steffen Vissing Andersen
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)