EggDoc Overview
EggDoc (see attached files) is a tool for generating documentation in HTML format based on information contained in specially-formatted comments in the scripts within an Eggplant suite. To use it, simply run the EggDoc script. You will be prompted to select the Eggplant suite for which documentation should be generated. To see an example of what the generated documentation looks like, run EggDoc and select the suite containing the EggDoc script itself.
The EggDoc script creates a folder (within the Sites/ScriptCatalogs folder within your home folder) for each suite that it processes. This folder 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 file for each 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. Comments that are recognized and processed 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. *)
That’s all that is needed. In addition, 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.
The first documentation comment (typically at the very beginning) of a script will be taken as documentation for the script as a whole, as long as it does not include a handler “definition” attribute either directly or indirectly, as described below.
Each documentation comment after the first one in a script (and the first one as well, if it comes immediately before the start of a handler or the “params” declaration at the start of a script) is taken as documentation for a handler. The documentation comment should come right before the start of 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.
So, 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
Because the text contained in documentation comments ends up in the generated HTML file with very little processing by EggDoc, you can include many HTML tags (such as bold and italics, or even hyperlinks) 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.
[Note: 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.]
Here is an example of a documentation comment containing a number of tags:
(** Handler y extracts and returns the useful information from t using u and v as appropriate.
@param t the source text from which to gather information
@param u the user name
@param v additional values -- this parameter is optional
@returns a list of all extracted values, or empty on error
@version 1.02
**)
to handle y with t,u,v
-- 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.
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.
@returns or @return 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, this information will be extracted from the script, by looking at the next non-blank line immediately following the comment. The top-level comment for a script should not include this tag. If the next line after a top-level comment is recognized by EggDoc as a handler definition, you will need to insert something else (such as an ordinary comment) following the top-level documentation 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.
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 to get you started. 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 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 all 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.