This implementation of Ygdrasil software is comprised of a core YG component and open source DSO modules. Users are encouraged to add to the existing documentation and to add other useful modules to the software library.
All of the code specific YG documentation is produced directly from the source files. The message syntax, event arguments, and key types are all extracted directly from the C++ code. All the other documentation including the commenting, descriptions, and categories are all taken from comments included within the source C++ code.
Contributions to the library can be made with the following procedure:
Comments within the C++ source file are used to generate the documentation for each node.
All comments before a class method definition are assumed to be the documentation heading. These comments are placed at the top of the documentation page with the comment indicators removed. Both C and C++ style comments can be used. Any HTML tags imbedded within the comments will subsequently be interpreted by the browser. As a result, the unordered list tag has been used to create a series of notes within the heading of each documented node.
The parsing system looks for a pre-defined set of tags followed by a semi-colon within the comments. These tags currently include Description, Category, Author, and Revision. The description and category tags are used to organize and briefly describe the function of each node. Documented nodes that do not include a category tag will not be included in the main index page. New categories can be added by editing the index template file, /usr/netusr/www/yg/ygIndex.templatel. The revision tag is used to generate a listing of revisions in cronological order. Revision tags must begin with a date of the form MM/DD/YY.
All intra-code comments not associated directly with a message, event, or key with be used to construct a comment tree of the code. Each if, while and for statement starts a new subheading of comments. Comments that give a general overview of the each class method will help users to better understand the actual implementation of the node they are using. Furthermore, the comments in the reset method are critical to establishing the default state of the node.
The YG documentation system is a generalized C++ parsing engine that has been extended to generate documentation for YG messages, events, and network keys.
Parsing the meaning of YG messages requires that code adhere to the following general guidelines:
Message argument syntax is a combination of argument types and the following logical separators in decreasing order of precedence:
Ambiguous dangling-else structures are of the form:
if (msg == "clip")
if (msg.args.size() == 2)
setClip(msg);
else
msg.error(name(),"(wrong number of arguments)");
The C++ parsing algorithm used by the documentation system cannot resolve these structures and they should be clarified as follows:
if (msg == "clip")
{
if (msg.args.size() == 2)
setClip(msg);
else
msg.error(name(),"(wrong number of arguments)");
}
The documentation system cannot extract the type of arguments being used unless they are extracted from the message within the message method. As a result, the previous example should let the system know that two float arguments are required by including the method calls to the ygMessage as follows:
if (msg == "clip")
{
if (msg.args.size() == 2)
setClip(msg.floatArg(0),msg.floatArg(1));
else
msg.error(name(),"(wrong number of arguments)");
}
Optional message arguments can be indicated by extracting them from the message within an if-elseif-else structure. If the statements within the else section do not extract any arguments and they are not specifying the message error, then the other arguments will be considered as optional. The following example extracts a single optional argument:
if (msg == "wall")
{
if (msg.args.size() > 0)
setWall(msg.boolArg(0));
else
setWall();
}
The following example extracts a single argument that is not optional:
if (msg == "file")
{
if (msg.args.size() == 1)
loadFile(msg.args[0]);
else
msg.error(name(),"(wrong number of arguments)");
}
Comments immediately above the message name filter will be included with the message as follows:
//load the given case sensitive filename
if (msg == "file")
{
if (msg.args.size() == 1)
loadFile(msg.args[0]);
else
msg.error(name(),"(wrong number of arguments)");
}
//set collision detection status
else if (msg == "wall")
{
if (msg.args.size() > 0)
setWall(msg.boolArg(0));
else
setWall();
}
Event names are extracted by either finding text in the eventOccured message or by resolving the ygString argument. The resolution of ygStrings involves the processing of the statements such as:
ygString myString("yg");
myString += "String";
Event arguments are resolved in a similiar manner with the portion before each equal sign being interpreted as the argument name. The following eventOccured method call will generate two event arguments named wand and user:
ygString myArgs("wand=wand1 user=user1");
eventOccured("enter",myArgs);
Comments immediately above the eventOccured method call will be included with the event as follows:
//the switch has turned on
eventOccurred("SwitchOn");
Network key names and data type are found by examining the addNetKey method:
addNetKey("matrix",&p_->matrix,YG_NET_MATRIX);
Comments immediately above the addNetKey method call will be included with the event as follows:
//create a network key for switch state
addNetKey("state",&switchState,YG_NET_BOOL);
Scripting examples are an important part of the documentation system. An example scene file should be created for each new node added. The name of the file is file.scene where file is the name of the new node. The example file should include comments and should run standalone executed.
When code has been thoroughly tested in a separate environment and completely commented it can be included in the library along with an example scene. The location of the Ygdrasil modules is /usr/local/yg/modules. A copy of the source file, header file, shared object file and dependency file (if necessary) should be placed in the modules directory. The example scene file should be placed in /usr/local/yg/examples. The system documentation can then be generated by executing /netusr/www/yg/YGDOC. This script will execute the documentation system and produce all of the HTML files again. If properly commented, your new node should appear in one of the categories listed on the index page at www.evl.uic.edu/yg.
All revisions/changes should be documented in the C++ code heading in the cxx file.
Move the previous revision below the revision tag so that the most recent revision is immediately following the tag.
Once fully documented, this code library should not require much maintenance.
The source code and examples are backed up each day and each month to a series of backup directories at
/netusr/www/yg/backup.
If you have further questions or comments about the library
please feel free to contact me at ahill@evl.uic.edu. Special
thanks to Crystal Wilson for banner and sub-heading graphic
design.