Difference between revisions of "D4Science Manual and API documentation Guidelines"

Latest revision as of 18:57, 6 July 2016

Introduction

The goal of this page 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 D4Science.

General Assumptions

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, and the tool used, through the gCore framework, for parsing WSDL descriptions and generating source stubs is the Apache Axis WSDL2Java (currently in version 1.2RC2).

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 D4Science the following three manuals are available:

• Administrator's Guide – Provides detailed instructions for installing and initializing a gCube based VRE. 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 deployed infrastructure.
• User's Guide – Targeted towards the VRE end-users. Provides instructions for using the VRE's end-user facilities, especially concerning the available User Interfaces (web portals, portlets etc). The document should also reference known problems, limitations, problem reporting etc.
• Developer's Guide – Documents technical-oriented information that will help developers further extend and exploit gCube and gCore systems' source code. 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. The document will target two classes of programmers:
  • Those who want to reuse the code – Programmers who will use gCube and gCore libraries to build their own tools, without need to have access to the source code.
  • Those who want to modify/extend the source code – Programmers who will use the platforms' source code to extend it, fix it and/or port 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.

Under Update Sections

In order to have a uniform appearance in the sections of the manuals that contain misleading or obsolete content, and are being updated, the mediawiki template:

{{UnderUpdate}}

can be used. By placing this command in the beginning of a page an appropriate disclaimer appears at the top of that page. All the under update pages are automatically listed in the UnderUpdate Category.

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

The importance of clear and fully documented code is revealed when a developer is trying to reuse or modify existing classes and packages. Below we define a minimum set of guidelines regarding how code should be documented:

• 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” ([1]) 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 D4Science’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 [2]
• Requirements for writing Java API Specifications [3]
• javadoc - The Java API Documentation Generator: [4]

WSDL Interfaces Documentation

WSDL provides some limited capabilities for including comments and documentation information. According to the version 1.1 ([5]) 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 the parsing performed by WSDL2Java, 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, used in the gCore framework.

In D4Science, 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 gCube's Process 
	Optimisation Library GenericPlanner.

	@author The D4Science 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 code

No automated procedure is applied for source code produced in the context of D4Science, 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.