Abstract
1. Introduction.. 
2. Notations2
3. Tool Usage9
4. Tool Structure9
5. Measurements12
6. Conclusion.. 12

Abstract

Documentation is the discovery and recording of software comprehension. Since software comprehension is the most expensive part of software evolution and maintenance, documentation and redocumentation is the key to software maintainability. This paper describes the process and the tool for documenting CLIPS and COOL CLIPS where the comprehension of the software is recorded in hypertext, in the style of the World Wide Web. The paper describes the tool “CLPDOC” which support documentation and redocumentation, and gives examples.

1. Introduction

Software documentation is part of software engineering. While engineering and reengineering may involve additional activities like refactoring, restructuring the code, retargeting, etc., redocumention only recovers the understanding of the software and records it, and therefore makes future program comprehension easier.

Program comprehension is the most expensive part of software maintenance, and therefore updated program documentation is the key to software maintainability.

Documentation and Redocumentation can either be done manually or it could be automated. In a stable environment a manual documentation or redocumention is commonly used; where in an environment that is rapidly changing, manual documentation and redocumentation would require extra resources and it becomes very costly to the project. Automating documentation would cut on cost by saving time and resources.

Since the introduction of the World Wide Web, hypertext has become a very popular and familiar technology. The basic tools such as the html language, browsers, Java applets, etc. are widely available and understood by all programmers. The same technology can be used in software documentation. The hypertext in which documentation can be accumulated is practically unlimited, ensuring that there is no need to be overly restrictive over the issue of what will be recorded. The key to the successful use of this technology is the structure of the documentation, which must support easy access to the information which the programmer needs and trusts.

The structuring of the hypertext documentation we describe here is similar to a JavaDoc (A famous Java documentation Tool). The information is divided into annotations of individual program types (rules, facts, classes, functions, templates, etc.). For each type in a given file, there is a table that contains all the elements of the specified type in the given file. The documentation partitions are browsed by standard hypertext browsers known from the World- Wide Web, such as Explorer, Netscape, Mosaic, etc.

In the next section, we describe the annotations and the tags used in documenting the code. Section 3 contains examples on the usage of the tool. Section 4 gives a brief description of the structure of the tool code. Section 5 describes a way of measuring the effectiveness and efficiency of the tool. Section 6 contains the conclusions.

2. Notations

CLPDoc support all types of CLIPS and COOL CLIPS (template, function, rule, facts, class, global, generic, massage-handler, instances). The annotation description of these types are based on the module that the type belong to.

The syntax for inserting documentation as a description for an element of any type is:

<@module-name typename Description @>

Example:

<@CONVERTER convert-new-order-template-to-instance Convert facts from external template format to internal@>

The type name should be associated with a defined CLIPS type: (deftemplate, deffunction, defrule, deffact, defclass, defglobal, defgeneric, difmassage-handler, definstances).

The three example below are correct syntax:

;-----------------------------------------------------------------------------------------------------------

; <@MAIN FUNC-int-good-bad

;Validates whether tag consists of only integer values@>

;-----------------------------------------------------------------------------------------------------------

(deffunction FUNC-int-good-bad (?intString)

(bind ?intLength (str-length ?intString))

(bind ?counter 1)

(loop-for-count (?cnt 1 ?intLength) do

(if (integerp (string-to-field (sub-string ?counter ?counter ?intString)))

then

(bind ?counter (+ ?counter 1))

( FUNC-price-good-bad bla)

(FUNCinstrumentID kk)

else

(return FALSE)

)

)

(return TRUE) )

;-----------------------------------------------------------------------------------------------------------

;<@ CONVERTER FUNC-price-good-bad (Range -999,999.99 thru 999,999.999) ;Validates Price type tag

 

(deffunction CONVERTER::FUNC-price-good-bad (?priceString)

(bind ?price (string-to-field ?priceString))

(printout t ?price crlf)

(if (and (> ?price -1000000)

 (< ?price 1000000))

 

Then

 (printout t "TRUE" crlf)

(return TRUE)

else (printout t "FALSE" crlf)

(return FALSE) ) )

; <@MAIN FUNC-qty-good-bad Quantity type tag for Validations@>

 

(deffunction FUNC-qty-good-bad (?qtyString)

(bind ?qty (string-to-field ?qtyString))

(if (integerp ?qty) then (if (and (> ?qty 0)

(< ?qty 999999999)) then (return TRUE)

 else (return FALSE) )

else (return FALSE)

)

)

 

3. Tool Usage

 

CLPDoc is designed as a friendly user tool with an easy to navigate GUI. The interface of the tool is shown in Figure 1.

 

FIGURE 1: TOOL INTERFACE

To navigate though the tool and use it functionalities, a user should parse a CLIPS code and then view the result. To parse a CLIPS code, select File-> Parse, see figure 2.

 

FIGURE 2: PARSE

After you press on Parse, a file chooser window will popup for you to browse and navigate to the folder that contains the CLIPS code. Figure 3 and Figure 4


 

FIGURE 3: FILE CHOOSER

 

FIGURE 4: NAVIGATE

When you reach the folder that contains the CLIPS code you need to document, the file chooser will show you all the CLIPS files under that folder; Figure 5. Select any of these files and click open, the tool will parse all the CLIPS files under that folder and generate documentation for it.


 

FIGURE 5: CLIPS FILE SELECTOR

To view the result select from the toolbar, View ->Results; Figure 6.

 

FIGURE 6: RESULT VIEWER SELECTOR

If the user selected to view result before parsing the code, a message will popup stating to the user the correct use of the tool; Figure 7.

 

FIGURE 7: RESULT VIEWER MESSAGE


 

The result will appear in an HTML format; Figure 8. The left frame contains the list of all the files that it generated documentation for. You can navigate through the documentation files by pressing on the file name and the results will appear in the right frame; Figure 9.

 

FIGURE 8: RESULT VIEWER INTERFACE


 

FIGURE 9: RESULT VIEWER NAVIGATION

As shown in figure 9, each element in a type table will have four documentation parts. The name of the element, the module the element belong to, the description of the element, and the list of possible dependencies for that element.

4. Tool Structure

CLPDoc is written in Java and it consists of 2 packages and 13 java classes. Figure 10 shows the package diagram of the tool, where figure 11 and figure 12 shows the UML class diagram of the tool.

 

FIGURE 10: PACKAGE DIAGRAM


 

FIGURE 11: UML CLASS DIAGRAM FOR PARSE PACKAGE

 

 


 

FIGURE 12: UML CLASS DIAGRAM FOR HTML PACKAGE

5. Measurements

For each element dependencies task, the following three numbers are retrieved: the number of dependencies suggested by CLPDoc, the number of relevant dependencies, and the number of relevant dependencies suggested by CLPDoc. The first of these numbers is dependent purely on CLPDoc, while the remaining two numbers are produced by the programmer using it. As such, they are dependent on the user and his/her experience. Together they measure how well CLPDoc supports the human user.

Using these three numbers, we computed the recall, and precision. The formulas are the following:

A recall rate is the percentage of relevant dependencies suggested by CLPDoc. Of the two measures, it is the most important one. Low recall rate means that the programmer must search the whole system for the missing dependencies. He/she has to use some other ways to find the dependencies, for example, read the source code or use some utility tool. A low precision means that CLPDoc recommends irrelevant dependencies.

In an ideal world we would like to have a 100% on Recall and 100% on precision. In the current version of CLPDoc, the Recall percentage is close to 100%, but the precision percentage is not. We have a high Recall with a medium high recall.

6. Conclusion

Automating the process of documentation is not a new idea, it has been used extensively and it is supported by tools that work with most major programming Languages.

In our experience, automating the process of documentation, proved to be a superior way to document software. In this paper, we described the notation used in documenting CLIPS and COOL CLIPS code, as well as the CLPDoc tool that support these notations.