Documentation

The documentation framework is based on JavaDoc’s specification provided by Sun Microsystems, Inc. Please follow their recommendations in writing comments.

Purpose

The main purpose of documenting a Zim class is to communicate the API. In the example below, the method mAddItemToCart belonging to the class zMakeAnOrder will add a product to the current shopping cart. This method requires one parameter, ProductID, and returns the set sShoppingCart.

General Comments

General comments to clarify code blocks is encouraged. Single comments start with "%" and are indented to the line that they refer too. A single "%" is used at the end of each comment to separate the comment from the code block.

% The following routine only runs on Wednesdays

%

if $weekDay($date) = 4

  let aCustomer.LastName = 'Rankin'

  zCustomer('delete', 'CustomerUI')

endif

Class Comments

Documentation scoped for the entire class is placed at the top of the source file. A brief description of what the class does is followed with the @author and @version tags. Rather than using an author’s name, the author’s email address is used.

4.5.4 Method Comments

Each method has a description explaining its purpose. A short description is provided and a long description can be added with a line between.

%-------------------------------------------------------------- method mAddItemToCart(viSelf) % Adds a product item to the shopping cart. % % This product is related to the shopping cart via the % the relationship Contains. %

Each parameter passed on the attribute structure has a description. Objects and parameters that are returned are noted by the @return tag. Exceptions that may be thrown in a method are noted by the @exception tag. Note that the attribute name, not the structure name is described for only attributes are passed in on the class attribute structure (i.e., zProduct would not accept attributes from the structure aCustomer).

% @param ProductID the product to add to % the shopping cart % @returns sShoppingCart the contents of the % customers shopping cart % @exception noRecordsFound thrown when a shopping cart does not exist

endMethod is commented with the method name.

endMethod % mAddItemToCart

4.5.5 Tag Summary

A number of tags derived from the JavaDoc standard are used to document Zim classes.

Tag Name

 Scope

 Description

 

@author

 Class

 Author of the class.

 

@version

 Class

 Version of the class.

 

@template

 Class

 The version of the template to generate the class skeleton.

 

@zcs

 Class

 The version of ZCS that the class complies to.

 

@todo

 Method

 Denotes a task must be done before the class is published.

 

@param

 Methods and Constructor

 Identifies a parameter. If an abbreviation is used for the parameter name, a translation will follow.

 

@return

 Method

 The objects or parameters returned by a method.

 

@exception

 Method

 Specifies the exceptions a method may throw.

 

 

4.5.6 Example

The example below shows how all the documentation components look together.

% zMakeAnOrder handles the making of an order. zMakeAnOrder % communicates with zCustomer, zShoppingCart, and zOrder to % generate an order. zMakeAnOrder allows customers to add and % update their shopping cart. When a customer checks out, an % order is generated from the contents of their shopping cart. % % @author nhenry@ZIM Technologies.ca % @version 1.0, 21-May-99 %

%==============================================================

% Public Methods

%

%--------------------------------------------------------------

method mAddItemToCart(viSelf)

% Request to add an item to the shopping cart.

%

% @param ProductID the product to add to

% the shopping cart

% @returns sShoppingCart the contents of the

% customers shopping cart

% @exception noRecordsFound thrown when a shopping

% cart does not exist on error

change aMakeAnOrder \

  let oException = {$LastErrMessage where aMakeAnOrder.oException is $null, aMakeAnOrder.oException}

return

endOn

mGetShoppingCart(viSelf)

if aMakeAnOrder.oException > '' and aMakeAnOrder.oException <> \ ’noRecordsFound'

set exception error

  else

change aMakeAnOrder \

  let oException = $null

endIf

% if shopping cart does not exit for customer, add one

% if $lastmember(sShoppingCart) = 0

compute 1 sCustomer \

evaluate (let aShoppingCart.CustomerID = Customers.CC) zShoppingCart('add','')

if (let aMakeAnOrder.oException = \ aShoppingCart.oException) > '' set exception error endIf endIf

compute 1 sCustomer \ evaluate (let aShoppingCart.CustomerID = Customers.CC)

% check if the product is already in the cart, if it is, % update the quantity instead of adding the item to the cart % again % compute 1 sShoppingCart \ where Contains.CustomerID = aShoppingCart.CustomerID \ and Contains.ProductID = aMakeAnOrder.ProductID \ evaluate(let aShoppingCart.QtyReqd = Contains.QtyReqd + 1)

if $membercount = 0

zProduct('initAttr','') change aProduct \ let ProdCode = aMakeAnOrder.ProductID zProduct('find','')

if (let aMakeAnOrder.oException = aProduct.oException) > '' set exception error endIf

compute sProduct \ evaluate (let aShoppingCart.UnitPrice = \ Products.UnitPrice)

change aShoppingCart \

let ProductID = aMakeAnOrder.ProductID \

QtyReqd = 1

zShoppingCart('addItem','')

if (let aMakeAnOrder.oException = \ aShoppingCart.oException) > '' set exception error endIf

else

zShoppingCart('updateItem','')

if (let aMakeAnOrder.oException = \ aShoppingCart.oException) > '' set exception error endIf

endIf

endMethod % mAddItemToCart

Other methods for zMakeAnOrder would appear here.

%============================================================== class zMakeAnOrder(viMethod, viSelf)

mpMakeAnOrder(viMethod, viSelf)

case when aMakeAnOrder.pMethod = 'addItemToCart' mAddItemToCart(viSelf)

when aMakeAnOrder.pMethod = 'updateQuantity' mUpdateQuantity(viSelf)

when aMakeAnOrder.pMethod = 'getShoppingCart' mGetShoppingCart(viSelf)

when aMakeAnOrder.pMethod = 'checkOut' mCheckOut(viSelf)

otherwise zObject(aMakeAnOrder.pMethod, viSelf)

endCase

mpFinalize(viSelf)

endClass % zMakeAnOrder

4.5.7 Documentation Layout

Documentation must be laid out in the following format:

Column 1

 Column 3

 Column 15

 Column 35

 

%

 tag

 identifier description

  

 

%

 @param

 CustomerID

 ID for the customer.

 

 

The columns refer to the column number within the source code. Source code should not exceed 80 columns.