API workshop: Deep dive into Java

Download API workshop: Deep dive into Java

Post on 16-Jul-2015




3 download

Embed Size (px)


<p>PowerPoint Presentation</p> <p>API Documentation Workshop: Deep Dive into JavadocBy Tom Johnsonwww.idratherbewriting.comJanuary 24, 2015</p> <p>Tech writer as lolcat2Sample Javadoc comment</p> <p>Browse a full example from Oracle. See the Examples of Doc Comments section.http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#examples</p> <p>http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#examples3Full Javadoc example</p> <p>Java documentation itself is created with Javadoc (obviously).http://docs.oracle.com/javase/7/docs/api/http://docs.oracle.com/javase/7/docs/api/4Workshop sample code</p> <p>See http://www.oracle.com/technetwork/articles/java/index-137868.html for a full example.</p> <p>5Workshop sample Javadoc</p> <p>Default output from the standard Java doclet that parses Javadoc tags.How to import sample Java projectIn Eclipse, go to File &gt; Import.Expand General, select Existing Projects into Workspace. Then click Next.In Select Root Directory, select the sample_java_project folder in the workshop files.Click Finish.In the project, expand the javadoc_tags package and click the .java files to view them.Who uses Java + JavadocUsed by Java developers.The most common document generator for Java APIs.Supported by Oracle.Integrates directly into IDE that developers use.Format is familiar to Java developers.Output is skinnable but you cant add non-ref files to it.Comment style is highly similar to most other document generators.Do developers write the initial API documentation in the source code?9Who writes the Javadoc?Often engineers write reference documentation, but the Javadoc is often incomplete, unclear, inconsistent, or otherwise problematic.Some power API writers/developers might look at the source code and create documentation from scratch, but this is less common.Can tech writers contribute to Java reference doc?Java libraries are highly technical. You must understand Java to contribute substantially.One of the things tech writers can contribute is style, says Joe Malin.Javadoc style is highly structured. Youre not just editing grammar.What to look for in JavadocMissing doc. Lots of Javadoc is incomplete. Look for missing documentation.Consistent style. See if the existing tags follow Javas style conventions.Clarity. Some descriptions are unintelligible due to the curse of knowledge, but its hard to judge without a stronger grasp of Java.</p> <p>Note: Only public classes, methods, and fields get included in the Javadoc, so focus on these.</p> <p>Install Eclipse IDE for Java developers</p> <p>You need an IDE to work with Java source files. Eclipse contains the JDK. Eclipse is the most common.https://eclipse.org/downloads/packages/eclipse-ide-java-developers/keplersr1</p> <p>13Install the Java Development Kit (JDK)</p> <p>The JDK is included in Eclipse, but the JDK includes the JRE, which you may or may not have. Type java -version to check. http://www.oracle.com/technetwork/java/javase/downloads/index.html14Install Git</p> <p>You get source files using source control such as Git, Mercurial, Perforce, etc. (Type which git to see if you already have it.) http://git-scm.com/book/en/v2/Getting-Started-Installing-Git15Developers get files through source control software </p> <p>Copy the clone URL and enter git clone {url} in a Terminal prompt, replacing {url} with the actual URL.https://github.com/tomjohnson1492/apiworkshophttps://github.com/tomjohnson1492/apiworkshop16Activity: Get source code Open command prompt or terminal, cd to a convenient directory, and type git clone https://github.com/tomjohnson1492/apiworkshopOpen Eclipse, then File &gt; Import &gt; General and select Existing Projects into Eclipse. Select the directory for the eclipse project you downloaded in step 1.Javadoc overview</p> <p>Theres no search, but there is an index. You can choose frames or no frames.Browse classes from left pane (All classes) or by package. When browsing by package, you see a summary of all classes contained in that package.18Each class has 3 main sections</p> <p>Each class in the Javadoc has 3 main sections: Fields, Constructors, and Methods. They have a summary first and then link to detailed sections for each below.Easy way to preview JavadocLook in Javadoc pane at bottom of screen while using Eclipse.</p> <p>The Javadoc tab lets you preview what the Javadoc output will look like. Shows only the element your cursor is on.Java classesClasses are templates from which objects are constructed. Analogy: You download a resume template in Word, and then use it to create your own resume.The resume template still exists, but now you have an instance/object from the template that contains all the styles and elements from the template.Java classes (cont.)Another Example: From a Bicycle blueprint, you make 3 three bicycle objects: Trek, Raleigh, and Giant. The Bicycle class has a field called size and a method called roll.So each bicycle object inherits the size field and the roll method.Each object is independent of the class.Common termsInstantiation is the process of creating an object (an instance) from a class. When you instantiate an object, or instantiate the class, it means youre creating creating an object from a class.Classes are organized into packages (folders).What a class looks likepublic class ACMESmartphone { // fields// methods</p> <p>}Classes always say class. They have the same name as the file, and start with a capital letter. They dont take arguments, so no parentheses () appear after the class name.Public is an access modifier that defines who can access this class. All public classes are included in Javadoc. Private classes are not.The main methodIn the sample files, the App.java class contains the main method:</p> <p>public static void main(String[] args) { }</p> <p>The compiled Java program will look for the class containing the main method and the code there.Note: The App.java class isnt meant to be included in the Javadoc. Users will have their own application code where they call the Java classes from our Java API.Javadoc tags versus comments/** * * **/</p> <p>/***/</p> <p>//A slash followed by two asterisks indicates Javadoc content.Just one asterisk is a regular comment. Or two slashes.Class description/** * Works like a regular smartphone but also tracks roadrunners. * * The ACME Smartphone can perform similar functions as other smartphones, such * as making phone calls, sending text messages, and browsing the web. However,* * Note that the RoadRunner Tracker app requires you to be connected to wifi. It * will not work on cellular data. * * @author Tom Johnson * @version 2.0 * @since 1.3 */public class ACMESmartphone {</p> <p>// content for class }Javadoc content appears before the class.Short description ends with first period. Long description then begins.Use for paragraph breaks.Tags come at end.HTML tags allowed (e.g., , </p> <ul><li><p>)Short description</p><p>Short description of the class appears on Class Summary section of the package overview.Short + long description</p><p>Both short and long descriptions appear on the class page.Available tags for the description/* * @author Joe Developer * @version 2.0 * @see Dynamite * @since 1.3 * @deprecated Use the {@link Dynamite class instead}*/@param and @throws are used in methods rather than classes.See = See alsoSince = when the class was first included</p><p>Generating Javadoc</p><p>Go to File &gt; Export.Expand Java and select Javadoc. Click Next.In left pane, select the project &amp; package you want.In the right, select the check boxes next to the classes you want.Click Finish.Packages are folders for classes</p><p>This javadoc_tags package has two classes, summarized here.Activity: Generate a JavadocGo to File &gt; Export. Select Java &gt; Javadoc, and click Next.Select javadoc_tags and expand it.Select Dynamite and ACMESmartphone class check boxes.Click Finish.Compare how the classes listed in the source end up in the Javadoc.</p><p>FieldsFields are variables available to the class. Dont use any @ tags for fields -- descriptions only.Only public fields are included in Javadoc. (If there is no access modifier, the default is package-private, not public.)Many times fields are encapsulated with getter-setter methods, which means their values are set in a protected way.</p><p>Sample field/** * The coordinates where the nearest roadrunner is located. */public String LongLat = "Longitude = 39.2334, Latitude = 41.4899"; Almost everything has an access modifier (public, private) and a data type (String, int).ConstructorsConstructors are methods that create objects.Constructors have the same name as the class, but with () for arguments.Constructors initialize objects with values passed from arguments.Its a best practice to include a constructor even if its just the default.Sample constructorpublic class ACMESmartphone {</p><p>public ACMESmartphone(double model, String license) {this.model = model;this.license = license;}</p><p>}Constructors have the same name as the class, but they dont say class and they have () for arguments.When this ACMESmartphone class is instantiated, it will be initialized with model and license values.Sample constructor in actionpublic class App {</p><p>public static void main(String[] args) throws IOException {ACMESmartphone myACMESmartphone = new ACMESmartphone(2.0, "398978fdskj");}</p><p>}You create a new object called myACMESmarpthone here. Its a new instance of the ACMESmartphone class. Java methodsMethods are subprograms that a class can do.Methods take arguments.Methods often return values to their caller.</p><p>Example: A calculator class might have the methods add, subtract, divide, multiple.</p><p>add(a, b) {sum = a + b;}</p><p>Sample methodpublic class ACMESmartphone {public String findRoadRunner(String city, String state) {System.out.println("location: " + city + ", " + state); // more logic}}Methods appear inside of classes. They begin with lowercase and follow camelcase style. Methods accept arguments. The arguments get passed into the logic of the methods program. /** * Gets the geocoordinates of roadrunners based on your city and state. * * @param city the city you want to browse for roadrunners * @param state the state you want to browse for roadrunners * @return the coordinates of the roadrunner in your area * @throws IOException if you put integers instead of strings */public String findRoadRunner(String city, String state) {System.out.println("location: " + city + ", " + state);System.out.println("getting geocoordinates of roadrunner.... ");System.out.println("roadrunner located at " + LongLat);return LongLat;}Documented methodDescriptions for methods are similar to classes. But @ tags include param, return, throws. The methods code must match the tags or you get warnings in Javadoc.@param tag guidelines@param fuseLength the length of the fuse on the stick of dynamite </p><p>@param is followed by parameter nameDont specify data type since its shown in the methods argumentsWritten as a lowercase phrase, without a periodIf multiple parameters, arrange by order or arguments in the methodRequired even if no descriptions are presentValidated against code so doc must matchActivity 2Look at the location of the params in the java source code. Find the same params in the Javadoc output.Look at the location of the method descriptions in the Java source code. Find the same descriptions in the output.Look at the location of the return tags in the java source code. Find the same returns statements in the output.@return tag guidelines@return the image at the specified URL. </p><p>At end of method, return means it returns this value to the method that called it.Methods that dont return anything have a void modifier.Not followed by a specific word like @param is.Code must actually return something in order for this to validate in javadoc.@throws tag guidelines@throws IOException if your input format is invalid</p><p>Means if something goes haywire in the code, Java will flag the problem with a specific type of error in the error message.You add @throws tags to methods only if the method throws a specific error. Helps to pinpoint problems in code.Written with if clause as a continuous full sentence. Synonymous with @exception.</p><p>Adding linksYou can add links through the @link tag.</p><p>{@link Foo}{@link Foo#bar}</p><p>Here Foo is the class name, bar is the method name.Dont overpopulate docs with links, though. Use tags to set off class or method names.Javadoc checks to see if tags match code</p><p>The code doesnt have a blackPowder parameter in the method, so Javadoc creates an error when generating doc.Activity: Add a field and methodAdd an additional @param tag to the Javadoc.Regenerate the Javadoc.See if Javadoc generates an error and warning for the mismatched documentation. For more detail on Javadoc, see Oracles Javadoc guidelines page</p><p>Also see http://idratherbewriting.com/java-javadoc-tags/ for my own summary.Recognize these Java termsClass: blueprints for somethingObject: an instance of a classMethods: what the object/class can do Fields: variables in the object/classConstructor: a method to create an object for a classPackage: a folder that groups classesAccess modifier (e.g, public): the scope at which a thing can be accessedInterface: a skeleton class with empty methods (used for standardizing)Enum: a data type offering predefined constantsSubclass: a class that inherits the fields + methods of another classJAR file: a zip-like file containing Java classesWAR file: a compiled Java web application to be deployed on a serverDoclet: what parses the Javadoc tags and produces the Javadoc outputActivity: Add some contentAdd a new method to one of the classes by copying an existing method and changing some of the content. (Keep the access modifier as public.)Modify the description, some parameters, and return value for your new method.Generate the Javadoc and see your newly documented method.Doxygen</p><p>- Commonly used for C++.- Works with Java, C++, C#, and others.- Has easy front-end GUI.- Point it at your source files.- Automate into builds.- Can include non-source files (Markdown).- Frame-based output.- Can skin.Doxygen has GUI front-end</p><p>Specify the source directory of your files.Pitfalls with auto-doc to watch out forCons of in-source documentation</p><p>Subject to Curse of KnowledgeNot task-focusedSuffers from lack of ownershipDoesnt integrate with other contentGives illusion of having real docSince the reference doc is often written partly by engineers, you have to watch out for several pitfallsBiodiversity fail. By Martin Sharma. Flickr. http://bit.ly/1CodnKM55</p><p>A developer who creates the API may assume too much of the audiences technical ability. As a result, the descriptions arent helpful.Problem 1: Curse of KnowledgeThe Source of Bad Writing. Wall Street Journal. http://online.wsj.com/articles/the-cause-of-bad-writing-141166018856</p><p>Auto-doc is feature-based doc approach. Task-based doc includes multiple calls and workflows in support of goals. It might make use of several different objects and methods across the reference doc.Problem 2: Not task-focusedProblem 3: Lack of ownership</p><p>Auto...</p></li></ul>