ILEDocs

ILEDocs is a documentation tool which helps the software developers to document their programs in a convenient way. The program parses the source code and extracts the special documentation comments. Those comments are stored in a database file. From there they can be processed further into various formats, for example HTML.

Example

/** * \brief CEE Date API : Calculate week start and end * * <p> * This example uses the ILE CEE Date API to convert the current date * into a lilian date. The weekday is calculated through the API CEEDYWK * (1 - 7, 1 = Sunday). Then the week start and end is calculated. * </p> * * The following APIs were used: * <ul> * <li>Convert Date to Lilian Format (CEEDAYS)</li> * <li>Convert Lilian Date to Character Format (CEEDATE)</li> * <li>Get Day Of Week (Numeric) (CEEDYWK)</li> * </ul> * * \author Mihael Schmidt * \date 29.08.2007 * * \link http://www.rpgnextgen.com RPG Next Gen */

For a HTML documentation example take a look at the Linked List API documentation.

More on about available tags and requirements for RPG and CL can be found in the documentation which is shipped with the web application.

Installation

Parser

All necessary objects are contained in the save file like program, database file and sources. The program object is compiled with V5R3 as the target release.

Web application

First add the jt400.jar to the servlet containers common jars (for Tomcat 6.x put it under /lib/. You'll probably need to restart the server.

The web application is packaged into a web archive file (ILEDocs.war). You should be able to deploy it on any recent servlet container (f. e. Tomcat 5.x and 6.x). After deployment you have to change the settings for the database connection.

Tomcat 5.x/6.x:

go to the tomcat base directory
from there go to conf/Catalina/localhost directory and edit ILEDocs.xml

Change username, password and url according to your system environment. The my_lib part of the url should be the library where the database file ILEDBASE is stored.

Restart the web application.

If you are using Tomcat 5.x you can use the Admin web application of Tomcat to manage the database resources. There is no such application for Tomcat 6.x.

If you want to display another label than the library name you can map library no names in the file ILEDLIBS.

Configuration

The file ILEDCONF contains the tags used in the source and currently has one member. The program checks the current language settings and searches for a member for the language:

US = US english
DE = german

If it can't find a member for the current language settings it falls back to default (ILEDCONF member).

You can change the tags in the ILEDCONF file. It would probably be best to add a member for your language and let the ILEDCONF member be as fallback and as an example configuration (copy member ILEDCONF to US for example).

Download

The files can be downloaded in the download section.

How to use

The program ILEDOCS parses the source code and stores the data in the database file ILEDBASE. It is called in the following way:

CALL ILEDOCS PARM('MY_LIB' 'MY_SRC_FILE' 'MY_SRC_MBR')

TurnOver CMS

The parsing of the new or changed sources can be easily implemented through the usage of the exit point 1 - form finalization - where all the sources with the action CSCO (copy source and compile) are process with the ILEDOCS program. An example program will follow shortly.

How to create standalone HTML documentation

After filling the ILEDBASE database file HTML documentation can be generated from this data. For this you'll need the ILEDocs java client.

Download the archive file
Extract the content of the archive
Edit the database.properties file
Start the shell script with the parameters
1. library
2. source file
3. member

./start.sh MY_LIB MY_SOURCE_FILE MY_MEMBER

The parameters are the same as the ones for the ILEDOCS i5 program. The output is a HTML file with the same name as the member (member.html).

Future plans

ILEDocs on Sourceforge.net

One of the next steps will be to merge the source of this ILEDocs with the open source project ILEDocs on Sourceforge.net.

XML output

XML output is a nice thing if you want to create an offline documentation in one or more formats f. e. HTML and PDF. That would be a good use case for XML output as the XML document can easily be transformed with an XSL stylesheet into different formats with the help of the Apache FOP project.

Wiki output

It would be nice to have the program documentation side by side with the rest of the documentation in a wiki. If the wiki supports XML-RPC or SOAP (like Confluence or xWiki) for accessing the wiki then it would be no problem to add the program documentation with the usage of the HTTPAPI from Scott Klement.