JavaDoc: Generating API Documentation from Java Source Code, Slides of Java Programming

Download JavaDoc: Generating API Documentation from Java Source Code and more Slides Java Programming in PDF only on Docsity! JavaDoc 1 JavaDoc July 24, 2006 revision 1.2 – Jan 26, 2009 docsity.com JavaDoc 2 Outline  What is JavaDoc?  JavaDoc Comments  JavaDoc Tags  Generating JavaDoc Documentation  References docsity.com JavaDoc 5 What is JavaDoc? Advantages:  Program documentation process is coupled with the programming process  Automated generation of documentation: less error-prone  Ease of generation of documentation  Ease of update of documentation  Short code-to-documentation cycle: all programmers can be made aware of others’ developments almost in real time  Can generate highly browsable documentation, accessible electronically over the web (HTML) docsity.com JavaDoc 6 What is JavaDoc? Disadvantages:  There is a learning curve to learn how to use the tool, though it is minimal  Requires dedication, or else the documentation will be obsolete or incomplete. docsity.com " SIMIFGSBEVED Example: je This is the JINI Transport Agent implementation. It is implemented as a JINI service. The initial tasks performed by the class are: <ul> <1i>S5ets a security manager. <1i>Runs a listener for discovering the Lookup Service. <lisWhen LUS is discovered, registers with it —- publishes the Proxy. <1li>Connects with the Demand Dispatcher </ul> @author Your Name @since 1.0.0 eo ok *f public class JINITransportAgent implements Runnable & JavaDoc docsify com JavaDoc 10 JavaDoc Comments  Another useful HTML marker is <code>, which we can use to include a sample code in a JavaDoc comment. Any text between the <code> and </code> markers will appear in a Courier font. Example: docsity.com JavaDoc 11 JavaDoc Comments The generated HTML will be: docsity.com JavaDoc 12 JavaDoc Comments  For the JavaDoc comments to be recognized as such by the javadoc tool, they must appear immediately before the class, interface, constructor, method, or data member declarations.  If you put the JavaDoc comment for the class before the import statements, it will be ignored.  The first sentence is a “summary sentence”. This should be a short description of the element described by the comment. Note: JavaDoc does not provide a format for commenting elements within methods, i.e. the local variables and the computing going on inside the methods. But you still can use the regular comments marks // or /*..*/, to comment this part of your program. docsity.com " SEVERE CS Example: /** This class implements the backend interface. It i3 activatable. This is the class who is used by RMI to assure service-side execution. The compilation process (see comiple jta.bat) generates stubs from this class, which are transported to the client. Internally these stubs comunicates with the service JTABackend object. @author Your Name @version 1.0.0 @see JTABackendProtocol £ £ £ fF fF fF HF % *f public static class JTABackend extends Activatable & JavaDoc docdify com " SEVERE Generated HTML: public static class JINITransportAgent.JTABackend implements JINITransportAgent JTABackendProtocol, java lang Runnable This class implements the backend interface. It is activatable. This is the class who is used by RMI to assure service-side execution. The compilation process (see comiple_jta.bat) generates stubs from this class, which are transported to the client. Internally these stubs commnicates with the service JTABackend object. Version: 1.0.0 Author: Your Name See Also: JTABackendProtocol, Serialized Form JavaDoc docdiff .com JavaDoc 17 JavaDoc Tags @param Use this tag to add a parameter description for a method. This tag contains two parts: the first is the name of the parameter and the second is the description. The description can be more than one line. @param size the length of the passed array @return Use this tag to add a return type description for a method. This tag is meaningful only if the method’s return is non-void. @return true if the array is empty; otherwise return false docsity.com JavaDoc 20 Generating JavaDoc Documentation  After adding the JavaDoc comments to the source files, we use the javadoc command to generate the documentation.  We run the javadoc as we run javac or java tools.  After the javadoc command, we provide the parameters, when the mandatory ones are the either the package’s name or the source file (s) name. Example: In order to enforce JavaDoc to generate documentation for the complete GIPSY package, we write: javadoc gipsy In order to enforce JavaDoc to generate documentation for the JINITransportAgent.java file, to include the author and version tag and to include all the classes, attributes and methods we write: javadoc -private -version -author JINITransportAgent.java docsity.com JavaDoc 21 Generating JavaDoc Documentation Example: The source java file with built in JavaDoc documentation: JINITransportAgent.java The generated HTML documentation: JINITransportAgent.html docsity.com JavaDoc 22 • Sun Microsystems, “How to Write Doc Comments for the Javadoc Tool”, http://java.sun.com/j2se/javadoc/writingdoccomments/index.html • Emil Vassev, “DMS API Documentation”, Concordia University, Montreal, Quebec, Canada, 2005 • Wikipedia. “Comparison of Documentation Generators”. http://en.wikipedia.org/wiki/Comparison_of_documentation_generators References docsity.com