Documenting Scripts with EggDoc

Overview

EggDoc is a tool that generates documentation for all of the scripts in an Eggplant suite. Special comments within the scripts provide the information used to generate the documentation. The result is a collection of HTML files for each of the scripts in the suite.

The simplest way to run EggDoc is to type "EggDoc" in the Ad Hoc Do Box (at the bottom of the Run window). You will be prompted to select the Eggplant suite for which documentation should be generated.

Activating EggDoc via the Ad Hoc Do Box in the Run window

The EggDoc script creates a folder (within an "EggDocOutput" folder within your home documents folder) for each suite that it processes. The folder for each suite will contain a documentation file for each script in that suite, plus a master index listing all of the scripts, with links to the individual documentation files for each script.

To update the documentation for a suite to include the latest changes, simply run EggDoc again for that suite. The previous documentation for the suite will be replaced with the latest information from the scripts in the suite.

Ways to Run EggDoc

• EggDoc: When EggDoc is run without any parameters, it will display some brief information about itself and then prompt you to select the suite to document.

• EggDoc "/path/to/any.suite": Call EggDoc with the full path to a suite to generate documentation for that suite.

• EggDoc this: Call EggDoc with the word "this" to generate documentation for the current suite.

• EggDoc copy: Call EggDoc with the word "copy" to make a copy of the EggDoc script itself. This can be useful to look at as an example of how to use documentation comments (the script is thoroughly documented), and also allows you to modify the script to customize it for your own needs.

To see an example of what the generated documentation looks like, run EggDoc and select a suite containing a copy of the EggDoc script.

Documenting Your Scripts

To document your scripts, include special "documentation comments" at the beginning of each script, and also before each handler to be documented within a script. The special comments that are recognized by the EggDoc tool must begin with (** and end with **), like this:

(** This is a "documentation comment" in the format recognized by EggDoc for inclusion in the documentation of a script. **)

(* This is an ordinary comment. It will be ignored by EggDoc. *)

Each documentation comment may include a number of special attributes, identified by tag words beginning with @. These tags are described in the next section. For examples of documentation comments, look at the EggDoc script itself, which is well documented.

Well-documented scripts usually begin with two separate EggDoc comment blocks; the first one provides a description of the script as a whole, and the second one documents the initial handler, or the first defined handler in the script. It is strongly recommended that you include a top-level description for each script, because this description will also be used in the suite-level index of scripts.

ノート

If the first handler isn't documented with an EggDoc comment, you can include @definition script in the script description comment to ensure it is recognized as the script-level documentation.

Each documentation comment after the top-level script description is taken as documentation for a handler. The documentation comment should come right before the handler which it describes. In the case of an "initial handler" in a script, the comment should come just before the params declaration at the beginning of the script. If the initial handler does not include a params declaration, you should include a @definition attribute in that documentation comment.

In summary, a fully documented script containing multiple handlers would be organized like this:

(** Overall documentation for the script. **)

(** Documentation for the initial handler. **)
params a,b,c
-- initial handler code is here

(** Documentation for handler x. **)
to handle x q,r,s
  -- handler x code is here
end x

(** Documentation for handler y. **)
to handle y t,u,v
  -- handler y code is here
end y

Special Formatting in Comments

Documentation comments can include bold, italic, and code portions of text, using Markdown conventions:

• Italicize by surrounding sections with single underscore or asterisk characters: _ or * characters
• Bold sections by surrounding them with double underscore or asterisk characters: __ or **
• Bold and italicise sections with triple underscore or asterisk caracters: ___ or ***
• Create code styling by enlosing sections in backtick characters like this: `code`.

Other than the simple markdown mentioned here, the text contained in documentation comments ends up in the generated HTML file with very little processing by EggDoc. This means you can include many HTML tags (such as <div style="color:red">red text</div>, or even hyperlinks or tables) in your descriptive text.

Information Tags

Each documentation comment may include a number of special pieces of information, indicated by tags beginning with an @ symbol. Each tag is listed on a separate line after the text of the description.

ノート

This format was chosen for its familiarity for those who have used similar documentation-generation tools for other languages, such as Javadoc for Java, PythonDoc for Python, JSDoc for JavaScript, etc. However, some of the tags used by EggDoc are different, so be sure to read the following descriptions.

Example:

This example shows a documentation comment containing a number of tags:

(** Handler y extracts and returns the useful information from tt using uu and vv as appropriate.
@param tt the source text from which to gather information
@param uu the user name
@param vv additional values -- this parameter is optional
@returns a list of all extracted values, or empty on error
@version 1.02
 **)
to handle y with tt,uu,vv
    -- handler y code is here
end y

EggDoc is very flexible about the special tags that can be used: any word that begins with @ at the beginning of a line will be treated as a tag word. This allows you to create any tags that are important within your organization. The same tag can appear multiple times within a comment (as seen for the @param tags in the example above). All of the information associated with a given tag name will be gathered together and presented in a single block in the documentation.

Tags With Special Meaning

Several tags receive special treatment by EggDoc. The following are descriptions of the tags that have special meaning:

• @param parameterName description, @params parameterName description:
  Describes a parameter to the script or handler. The next word should be the name of the parameter, followed by a description of that parameter. You should include a @param tag for each parameter expected by your handler, in the same order that they are passed to the handler. Be sure to include the parameter name following the tag, and then the description of that parameter. Either @param or @params may be used. EggDoc consolidates all of the parameter descriptions under the heading "params" in the documentation.

• @return description, @returns description:
  Describes the type of information returned by a script or handler. You should include this information for any handler that returns a value. Either @return or @returns may be used.

• @property propertyName description:
  Describes a property of the script object. The next word should be the name of the property, followed by a description of that property. This would typically be used only in the top-level comment for a script.

• @definition handlerDeclaration:
  Contains the definition of the handler being documented. For example: "to handle countMoney account, type". Use this tag if you want to provide a different definition than the actual definition in the script, or to include documentation for a handler which is not present in the script, such as one supplied by a helper.

ノート

If a @definition tag is not included, the definition will be extracted automatically from the script, by looking at the next non-blank line immediately following the comment. The top-level comment for a script should use @definition script or may omit the @definition tag provided the first handler in the script has its own EggDoc comment.

• @description:
  EggDoc treats the first part of a documentation comment, up to the first tag, as a "description". You may include additional description text later in the comment, following other tags, by explicitly including a @description tag. All text following this tag until the next tag (or the end of the comment) will be appended to the description.

• @endOfDoc:
  This tag is a special signal to EggDoc to stop processing this particular documentation comment. The rest of the comment is ignored.

Other Suggested Tags

The following are some other commonly used tags that you may want to consider using in your documentation. These tags do not receive any special treatment by EggDoc, and you are welcome to add your own custom tags as well. This list is offered merely to give you some ideas. Tags will appear in alphabetical order in the generated documentation.

• @author authorName:
  Contains information about the author or authors of the script or handler.

• @see scriptOrHandlerName:
  Define a link to another handler or script that is related to the one being documented ("see also ..."). Any number of @see tags may be included.

• @version versionDescription:
  Contains information about the version number of the script or handler.

• @throws exception, or @exception description:
  Describes exceptions that may be thrown by the handler, which callers may want to be aware of.

• @deprecated deprecatedText:
  Indicates that the script or handler is deprecated and should no longer be used. The text may indicate an alternative script or handler that should be used instead.

• @copyright copyrightNotice:
  A copyright notice.

How it Works

EggDoc is a SenseTalk script. It breaks the work of creating the documentation down into two main steps. First, it parses each of the scripts in a suite to extract all of the relevant information that it can from the script itself and from the special documentation comments included in the script. Then it generates the actual documentation, using SenseTalk's merge() function to fill in templates using the information that was gathered in the first step.

This approach allows you to change the output format by changing the templates. In this version, the templates are built into the script itself. You can change them by editing the templates within the script. They are all located towards the end, in several handlers in the second half of the script.

To examine and customize the EggDoc script, run the command EggDoc copy to make your own copy of the script.