1. Today Javadoc. Packages and static import. Viewing API source code. Upcoming Topics: –protected access modifier –Using the debugger in Eclipse –JUnit testing Winter 2016CMPE212 - Prof. McLeod1

2. Winter 2016CMPE212 - Prof. McLeod2 Javadoc Javadoc.exe is a program that comes with the JDK. (It is in the same directory as javac.exe and java.exe – the “bin” folder). It is not included in the JRE only. If I have written a class, “ MyClass.java ”, that contains properly formatted comments (more below), then running “ javadoc MyClass.java ” generates a file “ MyClass.html ”. The html file contains external documentation generated from the formatted comments in the source code.

3. Winter 2016CMPE212 - Prof. McLeod3 Javadoc - Cont. Normal block comments in Java are delimited by “ /* ” and “ */ ”. Everything between these delimiters, usually multiple lines, is a comment. Javadoc block comments are delimited by “ /** ” and “ */ ”.

4. Winter 2016CMPE212 - Prof. McLeod4 Javadoc - Cont. The general form of a Javadoc comment: /** * Summary sentence. * More general information about the * class, attribute or method which * follows the comment, using as many lines * as necessary. (html tags can be included) * * javadoc tags to specify more specific * information, such as parameters and * return values for a method */

5. Winter 2016CMPE212 - Prof. McLeod5 Javadoc - Cont. The general form of a Javadoc tag is: @tagName comment The tags you use depend on what you are describing (class, method or attribute). In the case of methods, you can have a tag for each parameter, the return value, and a tag for each thrown exception. Eclipse (really nice!!) will generate a blank tag for you after you type “ /** ”. Typically, you will only write javadoc comments for public attributes and methods…

6. Winter 2016CMPE212 - Prof. McLeod6 Eclipse Javadoc Assist For example, if you have the method header: public static double[] generateRandomArray(int size) Type /** right above this line and press. You will get: /** * * @param size * @return */ public static double[] generateRandomArray(int size)

7. Winter 2016CMPE212 - Prof. McLeod7 Eclipse Javadoc Assist, Cont. Then you have to finish the comment: /** * Generates an array of random doubles. * * The method uses the Math.random() method to generate * an array of doubles between 0.0 and 1.0. * @param size The desired size of the array. * @return The array of random doubles. */

8. Winter 2016CMPE212 - Prof. McLeod8 Eclipse Javadoc Assist, Cont. Hold your cursor over the method header and you will get a preview of what the processed Javadoc will look like: (Or view the Javadoc in the same view as the Console tag.)

9. Winter 2016CMPE212 - Prof. McLeod9 Common Javadoc Tags @paramParameter_name description @throwsException_name description @returndescription @seepackageName.ClassName, packageNamme.ClassName#methodName, etc. @author @version

10. Winter 2016CMPE212 - Prof. McLeod10 Javadoc - Cont. Html tags can also be added to the comments to add more formatting to the resulting document: – for emphasis – for code font – for images – for bulleted lists –Etc…

11. Winter 2016CMPE212 - Prof. McLeod11 Javadoc Reference The best reference for javadoc is at: http://www.oracle.com/technetwork/java/javase/docu mentation/index-jsp-135444.html

12. Winter 2016CMPE212 - Prof. McLeod12 Javadoc - Cont. The output from Javadoc looks exactly like the API documentation you have already seen - since that is the way it has been generated! The advantage is that when source code is changed, the Javadoc comments can be changed in the source, at the same time. The external documentation is then easily re-generated. Javadoc also provides a consistent look and feel to these API documents.

13. Winter 2016CMPE212 - Prof. McLeod13 Javadoc - Cont. Most modern IDE’s (like NetBeans and Eclipse) allow you to run Javadoc from within the environment, and provide tools and wizards to help you create comments. In Eclipse, select “Project”, then “Generate Javadoc…”. Let’s run javadoc on the Halloween6 class. (Note that the first time you do this, you will have to tell Eclipse where javadoc.exe resides.)

14. Winter 2016CMPE212 - Prof. McLeod14 Packages “ package ” is a Java keyword. It provides a means of grouping classes together into a package. All classes in a package share some common theme. It is used as in: package package_name; This line is at the top of a class definition, before the public class…

15. Winter 2016CMPE212 - Prof. McLeod15 Packages and Eclipse Eclipse would prefer that you to create classes in a package. When you create a new Class, specify what package you want it to belong to. This will automatically add the package package_name; line to the top of the class, the proper folder is created in src, and the new class in saved in this folder. Eventually, you will create a *.jar (or *.zip) file with all the *.class files in your package. Put this user library somewhere in or below your classpath and then another class will be able to import it.

16. Winter 2016CMPE212 - Prof. McLeod16 Packages, Cont. The structure is: classpath\folder\packagename “folder” can be a series of folders. The import statement looks like: import folder.packagename.*; The “.* ” says to import all classes in the package, or you can import specific classes.

17. Winter 2016CMPE212 - Prof. McLeod17 Packages and Eclipse, Cont. You can add to the classpath by right clicking on Project - Properties to get the following window: Then choose “Add…”

18. Winter 2016CMPE212 - Prof. McLeod18 Packages, Cont. We have been importing existing packages already import java.util.Scanner; import java.io.*; …

19. Winter 2016CMPE212 - Prof. McLeod19 Packages, Cont. Note that Java automatically imports the java.lang.* package for you. This package contains many classes fundamental to the Java language: –String –Math –all Wrapper classes ( Boolean, Character, Integer, Long, Float, and Double ) –System, –and a few others…

20. Winter 2016CMPE212 - Prof. McLeod20 static Import Used to import some or all of the static members in a class, so that they can be used as if they were declared within the class that uses them. Example: import static java.lang.Math.*; Imports all methods and attributes in the Math class. See StaticImportMath.java.

21. Winter 2016CMPE212 - Prof. McLeod21 Aside – Viewing Java Source Code To do this you must have the file src.zip available. If you did not get it with the JDK you downloaded, you can download it separately and then put it in the root JDK folder, for example. The first time you try this in Eclipse you can click on a button that will allow you to specify the location of src.zip. Open the Libraries tree that is always part of your project to find the classes listed in the package of interest.

22. Viewing Java Source Code The first time you try this you will see: Click on “Attach Source…” Winter 2016CMPE212 - Prof. McLeod22

23. Viewing Java Source Code, Cont. Choose “External location” and click on “External File…” Winter 2016CMPE212 - Prof. McLeod23

24. Viewing Java Source Code, Cont. Go to the folder of your newest jdk and choose “src.zip”, then “Open”, then “OK”. Winter 2016CMPE212 - Prof. McLeod24

25. Viewing Java Source Code, Cont. Now you can view the source code files for any class in the API! (Can’t edit them, however…) Winter 2016CMPE212 - Prof. McLeod25

26. Aside – Protected Access So far we have used public and private access modifiers. protected is what you get if you don’t specify an access modifier. This means “ public inside the package, private outside the package”. Used in the API. Use sparingly! Winter 2016CMPE212 - Prof. McLeod26