developing sdk documentation with javadoc · developing sdk documentation with javadoc 4...

Developing SDK Documentation with Javadoc 1

Developing SDK Documentation with Javadoc Matthew SternSr. 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


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


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


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


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?

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.


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.


http://java.sun.com/j2se/javadoc/index.jsp

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

http://java.sun.com/j2se/javadoc/writingapispecs/index.html

http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/overview.html

http://forum.java.sun.com/forum.jspa?forumID=41

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.


http://ant.apache.org/manual/CoreTasks/javadoc.html

http://www.doclet.com/

http://www.filigris.com/products/docflex_javadoc/about.php

http://aurigadoclet.sourceforge.net/

http://www.swe.uni-linz.ac.at/research/jdcx/


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!


http://www.netbeans.org/

http://www.eclipse.org/

http://www.cppdoc.com/

http://ndoc.sourceforge.net/

http://www.stack.nl/~dimitri/doxygen/

http://www.innovasys.com/products/documentx.asp

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 to the instructions.



4. Run NetBeans. The NetBeans welcome page appears.

Opening the Anagram Game Sample

Do the following to open the Anagram Game sample:

1. Click Sample Project. The New Project window appears.

2. Under Categories, double-click Samples, and then click General. Anagram Game appears under Projects.

3. Click Anagram Game and click Next. You are prompted to specify the name and path for your project.

Note: Create a path in the root of your drive and do not use spaces in the name (like C:\NetBeansProjects\AnagramGame). This will make it easy to run the MIF doclet later on.

Click Finish to complete the wizard.

4. The Anagram Game appears on the Project and Files tabs on the left side of the screen.

Creating Your First Javadoc!

Now, try writing and generating some Javadoc. Follow these steps:

1. Open a source file. Click the Projects tab. Then, expand Anagram Game | Source Packages | com.toy.anagrams.lib. Underneath, there


is a source file, WordLibrary.java. Double-click WordLibrary.java. The file opens in the code editor on the right.

2. Try the AutoComment feature. Select Tools | AutoComment. The AutoComment window appears.

3. Select a class or member on the left side of the AutoComment window. The comments and tags appear. Edit the text as you wish. If you click the WordLibrary.java tab, you will see how the changes you make in the AutoComment window are reflected in the source code.

5. Generate the Javadoc. Make sure you have clicked the WordLibrary.java tab so that the source code is visible. (You cannot generate Javadoc from the AutoComment window.) Then, select Build | Generate Javadoc for “Anagram Game”. The console at the bottom shows the status of the Javadoc generation.


6. In your file system, go to the path you specified for your Anagram Game files. Then, go to the dist\Javadoc folder and open index.html. Your generated Javadoc will appear.

Using the MIF Doclet

With the MIF doclet, you can generate the Javadoc as a FrameMaker-compatible MIF file. Don’t have FrameMaker? Try Mif2Go by Omni Systems (http://www.omsys.com) to convert the MIF file to HTML, XML, Help, or Word.

Do the following:

1. Download the MIF doclet from the Sun Web site at http://java.sun.com/j2se/javadoc/mifdoclet/index.html.

2. Extract the ZIP file to the JDK folder (for Windows, C:\j2sdk1.4.2_07) and select the option to use the folder names saved in the ZIP file.

3. Create a batch file or script with the following commands:

javadoc ^ -doclet com.sun.tools.doclets.mif.MIFDoclet ^ -docletpath C:\j2sdk1.4.2_07\mifdoclet1.2\lib\mifdoclet.jar ^ -J-Xmx20M ^ -d docs ^ -sourcepath C:\NetBeansProjects\AnagramGame\src ^ com.toy.anagrams.lib


http://www.omsys.com/

http://java.sun.com/j2se/javadoc/mifdoclet/index.html

Make the following changes:

• If your JDK folder has a name other than C:\j2sdk1.4.2_07, change the path in the third line.

• In the sixth line, replace the path to your Anagram Game project, if different.

Save the batch or script file to the src folder for the Anagram Game (like C:\NetBeansProjects\AnagramGame\src).

4. Run the batch or script file. This creates a docs folder in your src folder (like C:\NetBeansProjects\AnagramGame\src\docs).

5. Open the docs\mif folder to see your Javadoc in FrameMaker-compatible MIF format.


developing sdk documentation with javadoc · developing sdk documentation with javadoc 4...

Documents