Strange Eons includes a built-in tool for generating documentation from a JavaScript file automatically. You can use this tool to create HTML documentation files for your JavaScript libraries similar to those provided in the plug-in kit. You can also get documentation for a library and display it in a window while SE is running using the Script Library Documentation Plug-in or the LibUtils.help function in the libutils library. The plug-in simply calls LibUtils.help() when it is activated. This window will list all "standard" libraries included with SE and any additional libraries that are registered with SE (see the libutils library for information).
You can start MakeDocs as a command line tool using the following command:
java -jar strange-eons.jar resources.libraries.MakeDocs sourcedir destdirWhere strange-eons.jar is the path to the SE JAR file, sourcedir is a directory of .js and .doc (documentation blocks without source code) files to convert, and destdir is the directory where the documentation files should be written.
Alternatively, the resources.libraries.MakeDocs class includes some static methods that can be used to convert JavaScript source on the fly. The method
void resources.libraries.MakeDocs.convertDirectory( File sourcedir, File destdir )
provides equivalent behaviour to the command line tool. Alternatively, the method
String resources.libraries.MakeDocs.convertFile( File sourcefile, File destdir )
converts a single source file instead of an entire directory, returning the library name as a string. This will not generate the CSS file that the page links to (but convertDirectory does). Finally, the method
String resources.libraries.MakeDocs.createHelpFile( String title, String source )converts JavaScript source code stored in a string into a string of HTML text that contains the documentation extracted from source. (The document's title is set with title.)
MakeDocs only processes comments that start with /**. Other text in the source file is ignored. Within such documentation blocks, processing is broken down into several sections: a signature line, one or more groups of description bodies, examples, and parameters, and finally a return summary. The middle blocks can be presented in any order, but are typically listed in the order indicated. Not all documentation blocks include an example, and documentation blocks for functions that take no arguments will not normally include any parameter blocks.
The first line of the comment should be a summary of the function or other concept being documented. For functions, this is the function's signature. For objects, it is usually just the name of the object. Text between parentheses (, ) is assumed to represent arguments to a function or method. Text between square brackets [, ] is assumed to indicate optional arguments. The sequence of characters " : " (space, colon, space) is used after an object name to name the object's prototype (as in Function : Object). The special identifier [static] indicates that a function is defined on the particular object instance specified by the summary, rather than on the prototype of that object. (This is similar to a static method in a Java class.) The special identifiers [ctor] and [class] indicate that the summary is the name of a "class", either a JavaScript constructor function ([ctor]), or a Java class ([class]). (JavaScript uses prototype-based inheritance and does not contain classes.) The identifiers [readonly] and [writeonly] indicate that a property only supports getting or setting, respectively. These annotations, if used, should appear at the end of the summary line.
This section provides a detailed description of the entity being documented. You should follow the normal rules of HTML, such as using <, >, &or to insert a <, >, or & symbol (respectively). To include segments of code, you can use either <code>...</code> or (as a convenience) <tt>...</tt>. A blank comment line will automatically cause a paragraph (<p>) to be inserted.
Example code should be surrounded by <pre> and </pre> tags that each appear alone on a line. Within such blocks, whitespace will be treated literally and special characters (such as <, >, and &) will be converted into appropriate HTML entities automatically. The contents of the block will have syntax highlighting applied to it, similar to that provided by the Quickscript window.
Lines that contain the sequence of characters " : " (space, colon, space) are used to describe the parameters of a function, and will be formatted in a special way. The name of the parameter is listed on the left-hand side of the colon, while its summary description goes on the right. You can end a line with ... to indicate that the description continues on the next line.
For functions that return a value, a final line that starts with the word "returns" and which summarizes the return value should be included at the end of documentation block. Functions that do not return a value may include a capsule summary of the function's effect instead. In either case, this should be a brief sentence fragment. This is optional, and is usually omitted if the text would be essentially the same as the description body.
This is a plug-in that allows you to edit the documentation blocks of a script interactively. You edit your script in the Quickscript window, and when the plug-in is activated it will generate a preview of the documentation block you are editing on the fly. The source code for this plug-in is included in the JavaScript folder.