D4Science Manual and API documentation Guidelines

Introduction

This document was delivered in the context WP1.8 task 1.8.2 “Integration of Manuals and API documentation”. The goal of this document is to provide guidelines and good practices relating to the production of manuals and API documentation for the software systems developed in the context of DILIGENT. This document is the evolution of the T1.8.2 Concepts document ([1]) having incorporated the comments and discussions that took place on-line and during the June 2006 TCom meeting in Frascati.

General Assumptions

The purpose of T1.8.2 is “to integrate and homogenize manuals and API documentation produced in other technical WPs”. Manuals and API documentation are crucial for a usable system, either from the final user point of view and the developers’ point of view. These documents will be produced within each technical WP of the project, following templates and guidelines defined herein. The task is also responsible to verify the consistency and quality of produced documentation material.

We make the following technical assumptions that pertain to all development activities of the project:

• Java is the primary language of implementation. As a consequence we consider trivial to utilize the Javadoc tool to automate the generation of API documentation
• WSDL 1.1 is the default specification for describing Web Service interfaces. All the services are WSRF compliant thus GT4 bundled Apache Axis WSDL2Java (currently in version 1.2RC2) is the tool that is used for parsing WSDL descriptions and generating source stubs.

Documentation Guidelines

In the following paragraphs we draw an initial set of guidelines for Manuals and API documentation format and integration process.

Manuals

In the context of DILIGENT the following three manuals will be developed:

• Administrator’s Manual – Provides detailed instructions for installing and initializing a digital library using DILIGENT’s core components. Includes information about external dependencies, known issues, incompatibilities, specific platform details etc. Offers guidelines and documentation for the every day administration and upgrading of the infrastructure and the deployed Digital Library itself.
• User’s Manual – Targeted towards the Digital Library end-user. Provides instructions for using the Digital Library’s end user facilities especially details regarding the available User Interfaces (search portlets etc.) as well as information for adding material in the library, indexing instructions, adding meta-information to inserted material. The document should also reference known problems, limitations, problem reporting etc.
• Developer’s Manual – Documents technical-oriented information that will help developers further extend and exploit DILIGENT’s source code. The document will target two classes of programmers:
  • Those who want to reuse the code – Programmers who will use DILIGENT’s libraries to build their own tools, without need to access the source code.
  • Those who want to modify/extend the source code – Programmers who will use the platforms source code to enhance it, correct it, adapt it to different environments and applications domains.

The Developer’s manual will complement the components API documentation providing examples, good practices and common pitfalls using them. The manual will also include whatever other implementation information was omitted in the source code documentation like for instance detailed references regarding the algorithms used and the theory applied for the component implementation.

Manuals will be written in Microsoft Word format with MS-Office 2000 compatibility enabled. Templates will be made available in the context of WP1.8. Contributors to the manuals should strictly follow the styles and format rules of the provided templates. If additional formatting styles are needed they will be requested from the manual editors who will be responsible to include them and provide updated templates. This way we will ensure the consistency and homogeneity of the resulted documents.

The templates will provide a general purpose content outline that should be followed as much as possible. Nevertheless, the variety and diversity of DILIGENT’s software, will require the inclusion of different information, and the omission of other. This is in principle acceptable and it is the task’s obligation to ensure that in any case the information provided is sufficient and well presented.

From the MS-Word sources we will manually generate the required PDF and HTML documents to be made available for distribution from the project’s web site. The resulted HTML output will be checked before publishing to ensure its readability and structural consistency.

API Documentation

API documentation guidelines define common practices and procedures for the annotation of the source code with documentation information and the automatic generation of human readable reports with details regarding the code structure and comments on the code design, internal logic, algorithms used etc. Below we provide guidelines for documenting Java and WSDL source code.

Java Source Documentation

Although the production of source code for the various project components is already half-way and a considerable amount of lines of source code have been written, it is important to define a minimum set of guidelines regarding how code should be documented. Towards this we propose the following:

• All source code should be fully and properly commented by including both implementation and documentation comments. Implementation comments help developers who have access to program’s source code, get a better insight to the inner implementation details. Programmers should also provide comprehensive documentation comments. These comments will be parsed by the Javadoc tool in order to produce API documentation in HTML format.
• Sun’s “Code Conventions for the Java Programming Language” ([2]) should be followed regarding all styles of comments (implementation and documentation). Code Conventions define also appropriate variable, method and class naming policies that help produce a clear, self-documented code.

Programmers should generate documentation for protected and public classes and members (the default behavior of javadoc). For programmers who want to reuse the binary distribution of DILIGENT’s libraries. Also the programmer should include documentation comments for private classes and members that reveal the internal logic of the component targeting those developers that may wish to modify the source of the component.

The following links provide essential reference material for writing documentation comments and using the javadoc tool:

• How to Write Doc Comments for the Javadoc Tool [3]
• Requirements for writing Java API Specifications [4]
• javadoc - The Java API Documentation Generator: [5]

WSDL Interfaces Documentation

WSDL provides some limited capabilities for including comments and documentation information. According to the version 1.1 ([6]) specification programmers can use the wsdl:documentation element to include relative information to any element of the interface description. The way this information is interpreted is left open to implementation and to the web services toolkit that parses them. In practice GT4’s parser ignores all documentation tags except those declared within the wsdl:operation element of the portType declaration section. This gives as the ability to pass documentation comments to the source files produced by WSDL2Java utility included with GT4.

In DILIGENT programmers should use the documentation element for annotating operation elements. Example of such comment:

<portType name="PlannerPortType">
<wsdl:operation name="createPlan">
	<wsdl:documentation>
	Creates multiple candidate plans given a bpel document and a wsdl document. 
           Applies a default policy that optimises the plans for performance.				
	    @param createPlanRequest
	    @returns createPlanResponse
	</wsdl:documentation>
<wsdl:input name="createPlanRequest" message="tns:createPlanRequest"/>
	<wsdl:output name="createPlanResponse" message="tns:createPlanResponse"/>
</wsdl:operation>

The above will generate the relevant documentation comments regarding the createPlanRequest() method which is included inside the PlannerPortType.java source file.

Other documentation should be applied regularly in the wsdl:types definition area describing the data types defined. Also documentation should be included at the beginning of the interface to define the purpose of the WSDL file, contact persons etc. For example:

<wsdl:definitions>
<wsdl:documentation>
PlannerService. Provides a Web Services frontend to DILIGENT's Process 
	Optimisation Library GenericPlanner.

	@author The DILIGENT consortium
	@version $Id:$
</wsdl:documentation>

Programmers may optionally use specialized tools to parse and generate WSDL documentation reports in html and/or MS-Word formats. Such a tool is Altova’s XMLSpy 2006 whose Home Edition can be downloaded for free from Altova’s web site: http://www.altova.com/download/xmlspy/free_xml_editor.html.

Other source codes

No automated procedure is applied for source code produced in the context of DILIGENT, written in different programming language other than Java or for interfaces described in other language than WSDL. Nevertheless, it is expected that programmers of these codes will use the appropriate facilities provided by the language to include documentation information inside the code. Documentation should be targeted to users of the application or for programmers that will in the future attempt to extend or debug the code.

ETICS guidelines

ETICS has been selected as the “continues integration” platform of the project. Our intention is to exploit the capabilities of the platform regarding the automated generation of source code documentation.

Towards this, the doc build command should be used to pass the documentation production command for a given configuration. The doc command can be either an invocation to javadoc as you would do it from the command line or an ant target invocation. The latter is preferable method but some effort is required to extend the build.xml with the respective target, if this has not been done already (for details see Appendix A – Generating the javadoc build target with Eclipse.).

The output should be directed to the /doc/api folder residing under the root directory of the component’s folder structure. Javadoc should generate documentation for protected and public classes and members (default behavior).

Documentation should be packaged together with the components binaries. For this reason the install build command in the ETICS module configuration, should contain the following command:

cp –R ${moduleDir}/doc ${prefix}

The above will copy the complete documentation to the ${prefix} folder for packaging by ETICS.

If other documentation material needs to be included in the build package it should be first configured as external dependency to the component and then referenced from within the configuration section of the component.

Visibility of Manuals and API documentation

An important aspect of documentation and manual productions procedures is to facilitate their discovery from the interested readers. Thus the visibility of the documentation material produced is an important aspect of the task. Towards this we define the following guidelines:

• API documentation should be made publicly available from the project’s web site in html format for on-line browsing and in zip/compressed format for download.
• The project’s public web site should be configured in this way so that it periodically fetches the produced documentation material from the output directory of the build machine to the public web site from where it will be distributed. In case that there is no security risk, the public site may point directly to the build output for the latest build.
• Manuals should be also made available in the web site. Moreover source code or compiled packages should be placed together with the manuals and API documentation.
• All manuals should be distributed in PDF format to ensure cross-platform compatibility. Optionally, manuals may be available in MS-Word (.doc) format.

Procedures

The Task 1.8.2 responsible will perform the following activities to ensure the applicability of these guidelines:

• Coordinate with the web site administrators to connect with the build outputs and update the API documentation files after each build.
• Supervise the development of the manuals. Task 1.8.2 will be responsible to collect contributions for various sections of the three manuals to ensure their completeness and to integrate them in one single document.
• Validate that the herein defined guidelines are followed regarding API documentation. Since it is time consuming to go through its source file we will sample periodically source files for investigation. Also the javadoc automatically produced API documentation will be sampled to ensure that it satisfies the requirements defined.

Appendix A – Generating the javadoc build target with Eclipse.

Open the target project and run the Project-->Generate Javadoc menu command. A wizard dialog opens up to guide you through the process. In the first step select the source path with the files you want to document. Live the “Use Standard Doclet” option as it as a and set the Destination folder to PathToProject/doc/api.

Figure 1 – Setting the Destination directory

Press next, give a title to your javadoc document and press next again.

Figure 2 - Setting the name of the document

In the last step check the option “Save the settings of the Javadoc export as Ant script”. Save the javadoc.xml in the root folder of your project and press Finish.

Figure 3 - Saving the output to javadoc.xml

The documentation will be generated together with the javadoc.xml. Unfortunately this buildfile cannot be used as it is with ETICS because it contains absolute paths in the classpath attribute. Nevertheless it is still useful in order to appropriately modify your original build.xml.

Copy the javadoc target from javadoc.xml to your build.xml. Delete the classpath attribute from the javadoc element and do one of the following:

a. If you have a <classpath> path element in your build.xml which includes all required jars needed to build the component, add a classpathref attribute to the javadoc target passing as value the name of the above-mentioned path element.

b. If the component is a WSRF service, copy the classpath sub-element from the compile target element and paste it as subelement to javadoc (don’t forget to wrap it with </javadoc> and close the nested element).

Now you can issue an ant javadoc _options_ on the command line, to generate the documentation (in _options_ you should include all references to external dependencies as you do to the regular ant build… dist… commands). Place this command in the component’s ETICS configuration and you are ready!