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.