Generating Class Documentation with GenDoc

Introduction

SAS/AF software includes GenDoc, an experimental documentation utility that enables you to generate HTML files that document class, interface, resource, and frame entries. The generated HTML files can be viewed with most Web browsers. You can use the documentation produced by the GenDoc utility to provide assistance to developers who use the components that you develop.

You can start the GenDoc utility in any of the following ways:

In the Class Editor, select FileSave As HTML.
In the Interface Editor, select FileSave As HTML.
In the Resource Editor, select FileSave As HTML.
In the Build window while editing a frame, select FileSave As HTML.
At the command prompt, enter
```
afa c=sashelp.aftools.scl2html.frame
```
You can use the interface to select the entry and entry type you want to document.
Use the experimental SCL function CreateDoc:
```
CreateDoc('catalog-entry-name', 'output-directory');
```
where catalog-entry-name is the name of the class, interface, frame, resource, or catalog you want to document, and output-directory is the local directory to which you want to direct the HTML output.
Use the SCL Static Analyzer and add the HTMLDIR= option to the CROSSREF statement. In the following example, output-directory is the local directory to which you want to direct the HTML output:
```
proc build batch;
     crossref proj=lib.cat HTMLDIR='output-directory';
run;
```

Tips for Writing Meaningful Metadata Descriptions

Because GenDoc reads the metadata that is associated with a class or interface, the quality and usefulness of the generated documentation depends on how much information you provided in your class or interface definitions. Complete and accurate descriptions of metadata items also make class maintenance and debugging easier, and they aid other developers who use your classes.

Before you use the GenDoc utility to generate documentation, be sure to include values for the Description metadata items in the following properties and/or property elements:

Attributes

In your description, include a clause that begins “Returns or sets...”. Since the elements describe things rather than actions or behaviors, it is also appropriate to omit a subject and verb and to simply use a noun phrase. For example, instead of “This attribute is a button label”, you could use “A button label”.

Methods

Since methods implement an operation, they usually use a verb phrase. While this may make methods “self-documenting,” you should try to extend this action with additional detail. Method descriptions typically begin with a verb such as “Deletes,” “Updates,” “Sets,” or “Returns.”

Method Arguments

Provide a description that begins with “Specifies” (when INOUT is “Input” or “Update”) or “Returns” (when INOUT is “Output” or “Return”), depending on how the argument is used in the method.

Method Return Argument

Provide a description that starts with “Returns.” Descriptive text that you supply for method return arguments appears only in documents that are generated by the GenDoc utility.

Events

Provide a description that indicates when or how the event occurs, such as “Occurs when ...”. “Attribute changed” events are automatically included for each attribute you add. These events are assigned a description in the form “Occurs when the ___ attribute is changed.”

Event Handlers

Provide a description that indicates how the event handler performs. Since event handlers respond to events, most event handlers use the form “Executes when the ___ event occurs.”

You may also consider these additional style guidelines:

Use phrases instead of complete sentences for property descriptions.
Use third person declarative rather than second person imperative. For example, a description should read “Gets the label” instead of “Get the label.”

What the GenDoc Utility Creates

By default, the GenDoc utility stores the HTML files that it creates in the directory that includes a classdoc subdirectory in the HELPLOC option. The HELPLOC option is a SAS system option that is defined or set in the SAS configuration file or in an AUTOEXEC file. You can also edit the HELPLOC option for the current SAS session by selecting Tools

Options

System. You can then expand the Environment control and Help nodes to modify the HELPLOC option.

The HELPLOC option should include at least two directory paths if you want to provide component documentation. One directory path identifies the online Help files that are shipped with SAS software. For example:

!sasroot\core\help

The second path must end with a directory named classdoc. For example:

d:\My SAS Files\classdoc

SAS must be able to write to this directory in order for GenDoc to create HTML files.

Since you cannot have two classes with the same name within a catalog, the GenDoc utility creates a subdirectory for the library and catalog under the classdoc directory that is listed in the HELPLOC option. The first subdirectory specifies the library. A second directory is created under the library directory and is named for the catalog containing the element that you want documented. For example, if you generated documentation for sasuser.myclasses.SalesObject.class, GenDoc creates the directory /sasuser/myclasses under classdoc.

The following list describes the types of information generated by GenDoc and the filenames of the resulting HTML documents:

GenDoc File Output

Documentation for...	Contains...
Class Entry	parent or ancestor information and all properties (attributes, methods, events, event handlers, and supported or required interfaces) defined for the class. HTML file:`classname.htm`
Interface Entry	parent or ancestor information and all methods defined for the interface. HTML file:`interfacename-intrface.htm`
Resource Entry	all class entries and interface entries included in the resource. HTML files:`resourcename-resource.htm`, plus an HTML file for each class and interface in the resource
Frame Entry	frame information and general attributes, the associated resource, and instance information for all visual and nonvisual components on the frame. HTML file:`framename-frame.htm`
Catalog	all class, interface, and frame entries stored in the catalog. HTML files:`catalogname-index.htm`, plus an HTML file for each class, interface, and frame entry stored in the catalog

For example, if HELPLOC is set to d:\My SAS Files\classdoc and you generate documentation for sasuser.myclasses.SalesObject.class, the following HTML file is created:

d:\My SAS Files\classdoc\sasuser\myclasses\SalesObject.htm

You can edit the HTML files to add other information, such as a complete description of a component.

GenDoc creates an index file that contains links to other files when you generate documentation for a resource or catalog. However, you can create your own HTML file to use an index if you want a more customized collection. To document a project or application, you can also create an HTML file that contains links to all of the necessary documents, or to the documentation for the catalogs and/or resources that are used by the project.

Making Class Documentation Available

After you have used GenDoc to create documentation for your components, you can make that documentation available to users of your components. Instruct your component users to include a path in their HELPLOC system option to the classdoc directory where you generated the class documentation. Depending on your system environment, you may have to copy the files to a new location that is accessible to all appropriate users.

After they set their HELPLOC options, they can access the generated documentation through the Class Editor, Properties window, Components window, and Class Browser in the same manner that help is displayed for SAS classes. For example, if you make documentation available for myorg.classes.SalesObject.class and the class has been included in a RESOURCE entry that is displayed in the Components window, a user can select the class in the Components window and then select Help on Class from the pop-up menu to display the documentation in a Web browser.

Of course, you can simply copy the generated HTML files to an accessible location on a Web server to make the class documentation available to any developer at any time, regardless of whether SAS is running. If you copy the HTML files, be sure to preserve the directory structure that GenDoc creates for the library-name and catalog-name that are associated with the class, interface, or resource. Unless this location is defined in a developer's HELPLOC option, the interactive help features will not work.