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

From Gcube Wiki
Jump to: navigation, search
 
(13 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
[[Category:TO BE REMOVED]]
 +
 
== Introduction ==
 
== 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 ([http://dlib.sns.it/bscw/bscw.cgi/d35034]) having incorporated the comments and discussions that took place on-line and during the June 2006 TCom meeting in Frascati.
+
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 ==
 
== 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:
 
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
 
* 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.
+
* 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 ==
 
== Documentation Guidelines ==
Line 15: Line 15:
  
 
=== Manuals ===
 
=== Manuals ===
In the context of DILIGENT the following three manuals will be developed:
+
In the context of D4Science the following three manuals are available:
  
* [[Administrator's Guide]] – 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.
+
* [[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 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.
+
* [[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 DILIGENT’s source code. The document will target two classes of programmers:
+
* [[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 DILIGENT’s libraries to build their own tools, without need to access the source code.
+
** 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 enhance it, correct it, adapt it to different environments and applications domains.
+
** 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.
 
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.
+
=== 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:
 +
<pre>{{UnderUpdate}}</pre>
 +
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.  
  
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 ===
Line 35: Line 36:
  
 
==== Java Source Documentation ====
 
==== 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:
+
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.  
 
* 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” ([http://java.sun.com/docs/codeconv/]) 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.  
 
* Sun’s “Code Conventions for the Java Programming Language” ([http://java.sun.com/docs/codeconv/]) 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.  
+
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:
 
The following links provide essential reference material for writing documentation comments and using the javadoc tool:
Line 46: Line 47:
 
* How to Write Doc Comments for the Javadoc Tool [http://java.sun.com/j2se/javadoc/writingdoccomments/index.html]
 
* How to Write Doc Comments for the Javadoc Tool [http://java.sun.com/j2se/javadoc/writingdoccomments/index.html]
 
* Requirements for writing Java API Specifications [http://java.sun.com/j2se/javadoc/writingapispecs/index.html]
 
* Requirements for writing Java API Specifications [http://java.sun.com/j2se/javadoc/writingapispecs/index.html]
* javadoc - The Java API Documentation Generator: [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html]  
+
* javadoc - The Java API Documentation Generator: [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html]
  
 
==== WSDL Interfaces Documentation ====
 
==== WSDL Interfaces Documentation ====
WSDL provides some limited capabilities for including comments and documentation information. According to the version 1.1 ([http://www.w3.org/TR/wsdl]) 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.
+
WSDL provides some limited capabilities for including comments and documentation information. According to the version 1.1 ([http://www.w3.org/TR/wsdl]) 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 DILIGENT programmers should use the documentation element for annotating operation elements. Example of such comment:
+
In D4Science, programmers should use the documentation element for annotating operation elements. Example of such comment:
  
 
<pre>
 
<pre>
Line 74: Line 75:
 
<wsdl:definitions>
 
<wsdl:definitions>
 
<wsdl:documentation>
 
<wsdl:documentation>
PlannerService. Provides a Web Services frontend to DILIGENT's Process  
+
PlannerService. Provides a Web Services frontend to gCube's Process  
 
Optimisation Library GenericPlanner.
 
Optimisation Library GenericPlanner.
  
@author The DILIGENT consortium
+
@author The D4Science consortium
 
@version $Id:$
 
@version $Id:$
 
</wsdl:documentation>
 
</wsdl:documentation>
Line 85: Line 86:
 
http://www.altova.com/download/xmlspy/free_xml_editor.html.
 
http://www.altova.com/download/xmlspy/free_xml_editor.html.
  
==== Other source codes ====
+
==== Other source code ====
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.
+
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 guidelines ==
Line 102: Line 103:
  
 
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.
 
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.
 

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.