Abstract
1. Introduction
2. Notations
3. Tool Usage
4. Tool Structure
5. Measurements
6. Conclusion
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.
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)
)
)
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
