This tutorial is geared toward people who have existing code that they want to process with Cocoon. This will probably involve some editing to the source code files, but shouldn’t require a major revamp. The tutorial will go through the basic steps in making your header files minimally compliant, and then proceed with describing other common, useful features. Refer to the other portions of the User’s Guide for more complete details.

 

Class Headers

The first thing to do is to make sure Cocoon will find all your classes. To do this, you have to ensure that each class is immediately preceded by a documentation block. Here is an example of a minimal documentation block:

 

 

/*
CLASS
    classname
*/

In this header, classname is the name of your class. Note that the word CLASS must start in the first column and be all upper-case. That’s all you need for Cocoon to recognize that a class definition has started.

You can embellish the comments which bracket the documentation header in any way you like, and add any number of documentation headings. For example:

 

 

/*-----------------------------------------------------------------

CLASS
    classname

    Here would go a one- or two-line summary of the class...

OVERVIEW TEXT
    Here would be some overview text...

AUTHOR
    Your name here

-----------------------------------------------------------------*/

Just remember that the documentation headers must start in the first column and be all upper-case.

 

Class Bodies

Cocoon expects to see certain things in the body of the class definition which help determine the scope of class members. Here is an example of how the important scoping items in the class body must appear:

 

 

class  classname
{
	.
	.
	.
public:
	.
	.
	.
protected:
	.
	.
	.
private:
	.
	.
	.
};

The public, protected, and private keywords can appear any number of times, as long as they start in the first column and have the colon “:” immediately following the word. The string “};“, again starting in the first column, marks the end of the class declaration.

By recognizing these scope identifiers, Cocoon will be able to partition the members into the correct category (public or protected) in the class member listings, as well as suppress the listing of all private members.

 

Member Sentinels

Once within the class body, Cocoon uses a sentinel string to recognize a member declaration. The default sentinel lesbian sex string it uses is ten contiguous slashes: //////////. So all you need to do is make sure that the declaration of each member is preceded by a line with the sentinel string. Here is an example of a minimal member declaration that might appear within a class body:

 

	//////////
    void Foo();

This will be enough to let Cocoon find and process the member declaration. However, you probably already have some documentation for each member function. If so, your formatting should probably look more like this:

 

	///////////////////////////////////////////
	//
	//  Documentation for the function...
	//
    void Foo();

If you have documentation interspersed with the function declaration, such as in this example:

 

	///////////////////////////////////////////
	//
	//  Documentation for the function...
	//
    void Foo(
	int	arg,		// description of the argument
	int	another);	// more argument description

the comments will be preserved in the documentation pages, so you don’t have to worry about moving them right away.

Note that the sentinel string can have anything following the ten / characters without interfering with the member identification. However, there mustn’t be any completely empty lines teen lesbian between the sentinel string and the code for the member declaration. Typedefs, enums, and data members can be recognized by Cocoon as well, as long as the member sentinel precedes the declaration.

If you’re working with an established code-base, you may already have standard headers for each member function. If this is so, you can just use one the customization options to redefine the sentinel string.

 

Library Documentation

For each library indicated in the configuration file, you are required to provide its name. Cocoon will produce a page for each library that summarizes all the classes, typedefs, enums, and global functions it finds. This page is named libname.html, where libname is the name of the library. (Note that library names cannot be the same as any of the class names…)

If you have a global function, typedef, variable, or enum, you can simply precede it by one of the member sentinels as discussed in the previous section. When Cocoon finds a member sentinel outside of the declaration of a class, it assumes that the member documentation belongs in the page that is generated for the library.

 

Keywords

Cocoon also produces a page named keyweb.html. This contains a cross-reference page. If you do nothing special to provide keyword cross-reference data, this page will simply contain a list of all the classes and libraries encountered.

To provide more cross-reference information, you can simply add a documentation heading called KEYWORDS to each class. Full information on how to do this provided elsewhere, but the cross-reference page was mentioned here to make sure you’re not too surprised when you see it.

 

Fancy Formatting

Those are all the basics that you’ll need for making your source code comply with Cocoon’s formatting conventions. However, there are a few additional, flashy, kind-of-fun features and capabilities you may want to know about early on. Most of the additional capabilites of Cocoon are triggered through the use of customization options in the configuration file. Here is a partial list of customizations to whet your appetite:

 

  • If all your clients are using browsers that understand the <TABLE> element, you can greatly improve the quality of some of the formatting in the Cocoon-produced pages. This can be done via the usetable customization command.
  • You can change various aspects of the graphic presentation such as the colors used, the , and someĀ  which appear in the pages.
  • You can specify an HTML file that will be included on every Cocoon-produced page. This can be useful for including standard navigation bars, copyright information, etc.
  • If the documentation for your source-code is heavily formatted using ASCII-art, lots of tabs, etc. and doesn’t come out looking real good once it has been HTML-ized, you may want to use theĀ  This will make all documentation text come out using the <PRE> element, so that all of your formatting will come through intact. If you wish, you can update the documentation at a later time to be more amenable to HTML.

In order to use these options you’ll need to define a configuration file and use it when. To get started though, you don’t have to use these options. To run cocoon for this simpler case, read on…

Generating the Pages

Once your source code is ready, all you need to do is run cocoon to generate the documentation pages. The simplest way to get started is to do all your code at one time as a single library. To do this, copy all the source to some directory that is accessible to your local Web server, and run the command:

cocoon -l libname

where libname is the name you want to give the library.

This will generate a documentation page for each class found, one for the the library itself, and another page for the keyword cross-reference information.

Formatting

The centerpiece of the Cocoon utilities is the program named cocoon. The cocoon program takes in a documentation configuration file which describes all the libraries to be processed, where to locate all the files, and the customization options to use. Once a configuration file has been created, invoking cocoon is done as follows:

cocoon configfile

The construction of the configuration files is the key to generating the documentation. Following is an example configuration file that contains the minimal amount of information necessary to process a single library:

 

			# An example of a minimal configuration file
    webroot  /users/kotula/public_html

    library  MyLibrary  /users/kotula/projects/cocoon  cocoon

The syntax for the configuration file is fairly straightforward. The two directives shown in the example describe where to put the output HTML files, and the name, source directory, and output subdirectory of the single library. These key components deserve a bit more explanation:

 

webroot directory_path
The given directory_path tells cocoon where to put the HTML files it generates. A full directory path must be specified–no relative paths allowed. All the HTML files produced by cocoon will go in this directory or in its subdirectories. cocoon assumes that the directory is empty and it can freely overwrite any of its existing contents.
library name source_directory web_subdirectory
This directive specifies information about the library to be processed. Any number of libraries can be given in the configuration file, but you have to have at least one.The name given can be any string which follows the usual rules for making a symbolic name: alpha-numeric characters, can’t start with a numeral, no spaces, etc.

The source_directory tells cocoon where to find the C and C++ header files for the library. A full path name must be given. All files with a .h, .H, .hpp, or .hxx extensions are copied from this directory into the webroot directory structure.

The web_subdirectory specifies the name of a subdirectory under the webroot where the HTML pages and source files for this library should be put. The subdirectory name can be any number of levels deep. For instance ‘dir1’, ‘dir1/lib1’, ‘dir1/dir2/lib2’, etc. cocoon will correctly create any needed subdirectories.

These are the basics for setting up a configuration file. Just specify all the other libraries you want to process. It is important that all these libraries be processed with one call to cocoon to ensure that all the hyper-links can be established between the libraries.

However… If you have just one library to process, setting up a configuration file is an unwelcome overhead. In this case, you can use a special short cut. Just go to the directory where you want the HTML pages to be created. Make sure there are copies of the .h files in that directory. Then issue the following command:

cocoon -l library_name

Where library_name is the name of the library. The HTML pages, library page, and keyword cross-reference page will be created on the current working directory.

 

 

Saving the Cross-Reference Data Files

In the course of processing, cocoon produces three cross-reference data files. Normally, cocoon deletes lesbian pic them when processing is completed. However, if you would like to save them for use in your own utilities, you can use the -x option when you invoke cocoon.

The three cross-reference files are:

 

classes.xrf
This file contains a list of the classes encountered, and the directory where they were found.
family.xrf
This file contains all the inheritance hierarchy information for the classes that are processed.
keyword.xrf
This file contains a list of all the uses of each keyword for each class.

All these files are plain text, and their formats are pretty straightforward.