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

Page 2 – Autumn 2009Steffen Vissing Andersen Online Help

Page 3 – Autumn 2009Steffen Vissing Andersen Help (documentation for classes and methods) Purpose: Want to see documentation for the class String

Page 4 – Autumn 2009Steffen Vissing Andersen Help (SHIFT + F1) SHIFT + F1  Click on String Open the javadoc help: Rightclick  "Open in Help Contents"

Page 5 – Autumn 2009Steffen 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 2009Steffen Vissing Andersen Javadoc-Help for String (Method summary)

Page 7 – Autumn 2009Steffen Vissing Andersen Javadoc-Help for String (Method details)

Page 8 – Autumn 2009Steffen 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 2009Steffen 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 2009Steffen 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 2009Steffen Vissing Andersen javadoc comments /** * A Student class representing a student Steffen Vissing Andersen 1.0, 30/11/2008, */ public class Student extends Person { private int studentNumber; /** * Three-argument constructor address the address name the name number the student number */ public Student(String address, String name, int number) { super(address, name); this.studentNumber = studentNumber; }

Page 12 – Autumn 2009Steffen Vissing Andersen javadoc comments /** the studentNumber */ public int getStudentNumber() { return studentNumber; } /** studentNumber the student number to set */ public void setStudentNumber(int studentNumber) { this.studentNumber = studentNumber; } }

Page 13 – Autumn 2009Steffen Vissing Andersen javadoc comments

Page 14 – Autumn 2009Steffen Vissing Andersen javadoc comments

Page 15 – Autumn 2009Steffen 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, The name of the The version of the Description of parameters for a Description of what is returned from a Description of the exceptions thrown by the A reference to something else Find more tags in the documentation The javadoc comments will be extracted of the javadoc tool

Page 16 – Autumn 2009Steffen 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 2009Steffen 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 2009Steffen 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 2009Steffen Vissing Andersen Debugging our solution You are here in the code: The Debug Perspective opens The variables

Page 20 – Autumn 2009Steffen Vissing Andersen Debugging our solution You can 1)step into 2)step over Next statement If 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 2009Steffen Vissing Andersen Debugging our solution Next statement This is from the API then step over step over

Page 22 – Autumn 2009Steffen Vissing Andersen Debugging our solution Next statement This is our own work (here the constructor), and we want to inspect this step into

Page 23 – Autumn 2009Steffen 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 2009Steffen 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 2009Steffen 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)