CompSci 4 27jd.1JavadocJavadocCompSci 4 27jd.2JavadocThe Planÿ What is Javadoc?ÿ Writing Javadoc commentsÿ Using the Javadoc toolÿ PracticeCompSci 4 27jd.3JavadocWhat is Javadoc?Javadoc is a way to comment your code that enablesautomatic generation of web pages that documentyour code.Why use Javadoc?ÿ It's much faster than generating webpagesdocumenting your code.ÿ It's standard documentation which means it's easyto use and the structure is given.CompSci 4 27jd.4JavadocWriting Javadoc Commentÿ Javadoc comments start with /** and end with */ÿ The placement of the comment is important.ÿ The following can be commented:þ classesþ methodsþ instance variablesþ static variablesCompSci 4 27jd.5Javadocpackage tipgame;/*** Used to enable timed events.* @author Jam Jenkins*/public interface Alarm{/** creates alarm */public void alarm();}Writing Javadoc CommentJavadocCommentsCompSci 4 27jd.6JavadocCommenting a Classÿ Put the comment immediately before the classdeclaration.ÿ Briefly describe the purpose of the class in 2-3sentences.ÿ Optionally includeþ @author tagþ @version tagþ othersCompSci 4 27jd.7JavadocCommenting a Class/*** This class uses polling rather* than events for keyboard input.** @author Jam Jenkins */public class Keyboard implementsCompSci 4 27jd.8JavadocCommenting a Methodÿ Put the comment immediately before the methoddeclaration.ÿ Briefly describe the purpose of the method in ashort phrase or 2-3 sentences. Include more detailif necessaryÿ Include these tags if neededþ @param name – describes parameterþ @return – describes the return valueCompSci 4 27jd.9JavadocCommenting a Method/** Simulates the surface normal used for* bouncing the moving object off of the* stationary object. Normal is in the* direction from the surface of the* stationary object to the center of the* moving shape's bounding box.* @param stationary the object not in motion* @param moving the object that will bounce* of the stationary object* @return the radians of the normal vector*public static double getNormalVector(Shape stationary,Shape moving)CompSci 4 27jd.10JavadocCommentingInstance and Static Variablesÿ Put the comment immediately before the variabledeclaration.ÿ Briefly describe the purpose of the variable in ashort phrase. Include more detail only ifabsolutely necessary.ÿ No tags needed.CompSci 4 27jd.11JavadocCommentingInstance and Static Variables/** shape should initially be centered at (0, 0) */private GeneralPath shape;/** transformed shape */private GeneralPath shapeTransformed;/** applied to the shape prior to drawing it */private AffineTransform transform;/** the fill color of the shape, black by default */protected Color color;CompSci 4 27jd.12JavadocFor more information...Visit the article:How to Write Doc Comments for the Javadoc Toolhttp://java.sun.com/j2se/javadoc/writingdoccomments/index.htmlCompSci 4 27jd.13JavadocGenerating HTML using the JavadocTool in Eclipse1. Highlight the project you want to javadoc in the Project Explorer2. Select File->Export->Javadoc3. Under the ‘Javadoc command:’ enter the location of javadoc if it is notalready there. The location should be something like:C:\Program Files\Java\jdk1.5.0\bin\javadoc.exe4. For the ‘visibility’ select Private5. Select ‘Use Standard Doclet’6. For the ‘Destination’, enter where you want the html code generatedto go. The html in the location you choose will be overwritten withthe javadoc generated HTML, so make sure not to choose a placewhich already has an index.html you’d like to keep.7. Click on ‘Finish’8. If you get the source files out of sync with file system error then sayokay, highlight your project, right click and select refresh. This willresync your files. Repeat the instructions above.CompSci 4 27jd.14JavadocPracticeÿ Put Javadoc comments in one of the previoushomework assignment's so urce code.ÿ Generate the javadoc HTML filesÿ Post the HTML files to your web site. Whentransferring the files, be sure to transport theminto an empty directory. DO NOT transfer themdirectly into your public_html page because thiswill overwrite your index.hml. Instead transferthem into a subdirectory of
View Full Document
Unlocking...