Developing SDK Documentation with Javadoc Matthew Stern Sr
Total Page:16
File Type:pdf, Size:1020Kb
Developing SDK Documentation with Javadoc Matthew Stern Sr. Technical Writer Kofax Image Products Overview • What SDK users expect • How documentation generators like Javadoc can help • How Javadoc works • Strategies for working with developers • How to integrate Javadoc to produce complete SDK documentation What SDK users expect • Current and complete API reference • Useful real-world code samples • Theory of operation • Dependencies Developing SDK Documentation with Javadoc 1 Challenges with SDK documentation • How to create a current and complete API reference when the code can change frequently • How to provide the API reference with other needed pieces of information How documentation generators help • Create an API reference from the source code • Produce documents in a number of formats • Generate an API reference each time the code is built • Enable developers to create a reference for their own code Documentation generators • Javadoc • CppDoc • NDoc • Doxygen • Innovasys Document! X • Key: Each documentation generator fits a specific programming language and target reader Developing SDK Documentation with Javadoc 2 Demo: Generating Javadoc • Examining source code comments • Modifying comments • Generating the Javadoc Who should write Javadoc? “Here at Java Software, the doc comments are not owned exclusively by writers or programmers, but their ownership is shared between them. It is a basic premise that writers and programmers honor each other’s capabilities and both contribute to the best doc comments possible.” Strategies for working with developers • Engineer writes – writer revises • Writer writes in source code with engineer input • Engineer and writer collaborate on specs, which become the basis for source code comments • Key: Pick the partnership that works best for you and the project Developing SDK Documentation with Javadoc 3 Limitations of Javadoc • Provides only an API reference • Difficult to present lengthy explanations Providing additional information • Overview topic • Create an external topic and link to it from the Javadoc • Incorporate Javadoc as part of an online help or printed guide Demo: Providing more information • Linking to an external HTML file from the Javadoc • Incorporating the Javadoc as part of a complete online SDK guide • Generating Javadoc in MIF format with a doclet to incorporate in a FrameMaker-based guide Developing SDK Documentation with Javadoc 4 Summary • Javadoc and other documentation generators save time in developing API documentation • Javadoc can keeps API documentation in sync • Javadoc is a collaborative effort • Javadoc provides a good API reference, but you need more material to create a complete developers guide Contact me E-mail: [email protected] Web: www.matthewarnoldstern.com Questions? Developing SDK Documentation with Javadoc 5 Developing SDK Documentation with Javadoc 6 Resources for “Developing SDK Documentation with Javadoc” Terminology Used in this Presentation..........................................................................7 Javadoc Information on the Sun Web Site...................................................................8 Other Sources of Javadoc Information...........................................................................9 Doclet Resources......................................................................................................................9 General Java Information .....................................................................................................9 Other Documentation Generators................................................................................ 10 Try the Demos Yourself!................................................................................................... 10 Terminology Used in this Presentation ANT A scripting language used to automate the compiling and building of Java programs. API (application program interface) A series of methods, routines, and other programming interfaces used for developing software programs. Developers who want to customize or add on to your program need a reference to the API so that their program can use the features of your software. Doclet A Java program used by Javadoc to render documentation in a certain format. Documentation generator A program that creates documentation by scanning the source code for methods, variables, and source code comments and producing it in a usable format. IDE (integrated development environment) Software for developing programs that has several tools integrated into it, such as a code editor, compiler, and debugger. Visual Studio, NetBeans, and Eclipse are examples. Javadoc The standard documentation generator for the Java programming language. The default format for Javadoc is HTML, but by using doclets, you can produce documentation in RTF, FrameMaker-compatible MIF, and other formats. Developing SDK Documentation with Javadoc 7 JDK (Java Development Kit) Sun Microsystems’ SDK for creating Java programs. The JDK includes Javadoc. SDK (software development kit) A package of APIs, programming tools, and documentation that enables developers to customize or add on to your program. Javadoc Information on the Sun Web Site Javadoc Tool http://java.sun.com/j2se/javadoc/index.jsp Home page with links to information about Javadoc and the latest Javadoc information. How to Write Doc Comments for the Javadoc Tool http://java.sun.com/j2se/javadoc/writingdoccomments/index.html Sun’s guidelines for writing comments for Javadoc, including when to use different types of tags and style conventions. Requirements for Writing Java API Specifications http://java.sun.com/j2se/javadoc/writingapispecs/index.html Sun’s guidelines for writing API specifications in general. This information will help you determine the amount and structure of information. Doclet Overview http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/overview.html How to create doclets. Includes some code samples. Java Forums - Javadoc Tool http://forum.java.sun.com/forum.jspa?forumID=41 Sun’s forum for Javadoc developers. Developing SDK Documentation with Javadoc 8 Other Sources of Javadoc Information ANT Script Options for Generating Javadoc http://ant.apache.org/manual/CoreTasks/javadoc.html Supported options and command syntax for generating Javadoc from an ANT build script. Doclet Resources Doclet.com http://www.doclet.com/ Links to a variety of doclet resources, including tools, downloadable doclets, and documentation for creating doclets. DocFlex by Filgris Works http://www.filigris.com/products/docflex_javadoc/about.php A graphic designer for creating doclet extensions. The interface enables you to modify options supported by doclets. AurigaDoclet by Auriga Logic http://aurigadoclet.sourceforge.net/ A Javadoc doclet that can generate Java API document in FO, PDF, PostScript, PCL, and SVG formats. Javadoc Doclet eXtension (JDcX) http://www.swe.uni-linz.ac.at/research/jdcx/ A small framework for building configurable and flexible doclets. Written by Rudolf Ramler of Johannes Kepler University, Linz, Austria. General Java Information New to Java Center on the Sun Web Site http://java.sun.com/ Starting point for all things Java. Get an introduction to the Java platform, follow a tutorial, and learn how to get started with Java. Developing SDK Documentation with Javadoc 9 NetBeans and Eclipse http://www.netbeans.org/ http://www.eclipse.org/ Free and popular open-source integrated development environments (IDE) for Java development. Other Documentation Generators CppDoc http://www.cppdoc.com/ Creates Javadoc-like API documentation for C++ and C#. NDoc http://ndoc.sourceforge.net/ Generates .NET documentation from Visual Studio code. Doxygen http://www.stack.nl/~dimitri/doxygen/ Generates documentation in HTML, RTF, or LaTeX format from C++, C#, or Java. Innovasys Document! X http://www.innovasys.com/products/documentx.asp Generates documentation from Visual Studio, COM components, databases, and XML schemas. You can visit their booth at the show. Try the Demos Yourself! You can perform the same demos shown in this presentation by downloading the free JDK and NetBeans IDE. NetBeans includes the Anagram Game program you saw in the demos. You do not need to know Java to perform these demos, but you’ll want to try learning some Java after installing the software! Developing SDK Documentation with Javadoc 10 Preparing for Installation The JDK/NetBeans bundle is available for the Windows, Linux, and Solaris operating systems and can be downloaded from the Sun Java Web site. Go to: http://java.sun.com Before you can download the software, you must register with the Sun Developer Network. Registration is free and only takes a few minutes. Click “Profile and Registration” below the Sun logo in the upper right corner of the screen and create a profile. After completing the profile, you will be automatically logged in. Click the Java logo in the upper left corner of the screen to return to the Java Sun home page. Installing NetBeans and the JDK You are now ready to install and set up the software. Follow these steps: 1. Under “Popular Downloads” on the right side of the screen, click “J2SE 1.4.2 SDK”. 2. On the “Download Java 2 Platform, Standard Edition, v 1.4.2 (J2SE)” page, click “Download J2SE v 1.4.2_07 SDK with NetBeans 4.0 Bundle”. 3. On the “Download J2SE v 1.4.2_07 SDK with NetBeans 4.0 Bundle” page, read the installation notes for instructions for your operating system. Then, download and install the software for your operating system according