I thought I'd write up a quick update on the Legals doc tools, since
we're only a couple of weeks out from the date when I promised to
deliver basic functionality.
The basic task is to update the RefGuide compiler to support our
JavaScript language changes (introduction of class declarations,
etc.), and to handle runtime-specific features. The RefGuide doesn't
work currently because it doesn't know how to parse the new class
declarations; the DevGuide doesn't work because it relies on the
RefGuide for cross-references.
I've been initially focused on a replacement for "jsdoc2xml.py", the
script that reads in the LFC and outputs XML-format documentation for
that library. The primary reason to replace it is that Legals uses
the ES4/AS3 class declaration syntax, so the script no longer has to
intuit class declarations from constructor function declarations.
It's also a nice opportunity to remove another Jython script with
something written in the same language as the compiler.
The replacement is called "es4doc" and is being written to mimic
javadoc in the hope that it evolves into a general-purpose tool that
is useful for most ECMAScript-4 dialects. The ECMA-262 committee has
draft materials specifying comment formatting conventions for javadoc-
style tools, and I'm tracking that document.
The current script handles class, function, and variable declarations
at the top level, and nested within class decls. I'm not yet parsing
comments, but I'm harvesting them and writing them out as-is in the
XML output.
The wrinkle, of course, is that Legals is multi-runtime. My
understanding is that we are using declaration-level conditionals to
specify runtime-specific behavior, like so:
if ($swf7 || $swf8) {
[...]
} else if ($dhtml) {
[...]
} else {
[...]
}
The script actually handles this pretty well now. It looks for
boolean literals ("true"/"false"), any of a known set of runtime
constants (currently $swf7, $swf8, $dhtml, and $jme), and simple
logic operations containing the above. I did this so could handle the
"$swf7 || $swf8" expression, and also so that we would properly
process the programmer's idiom of disabling a branch by adding "false
&&" to the beginning of a conditional:
if (false && $dhtml) {
[...]
} else {
[...]
}
Unexpected elements of a conditional expression are ignored.
This is all running now, verified against a test suite of JS code
fragment / XML pairs which are validated using Jing against a Relax
NG schema definition.
There are lots of next steps with this tool, but I think I'm going to
take a short break now and go over to the DevGuide in the hope that I
can temporarily disable its dependency on the RefGuide and get it
compiling. (The dependency is there to provide cross-linking from the
DevGuide to the RefGuide.) This will allow our doc folks to start
putting new text into the DevGuide sooner rather than later.
Once that is done, its back to es4doc. I need to start handling
include declarations, then actually parse comments, then start
running the tool against the LFC sources to shake out more bugs.
There are also two big manual tasks looming:
- If we want to adopt the ES4 comment-formatting conventions, we'll
need to take a pass through the LFC and update all comments to match.
ES4 uses the javadoc style, which only looks for "/** ... */" and
doesn't look for "// ...", whereas our current LFC uses "// ..."
almost exclusively and matches by proximity. I like our more casual
style, but I'd prefer to move to the more common convention in the
hopes that we can eventually share tools.
- I'd like to get rid of the wrapper pages altogether -- at least for
the LFC -- by adding that information into comments in the
corresponding LFC source files. This will reduce complexity and place
all reference materials (well, almost all) in the source files
themselves.
I also have one other ambition: to radically reduce the size of the
manually-written LZX schema, and use as much information as possible
from the LFC to derive it. Ideally the LZX core schema would only
include "special" syntax forms that are explicitly processed by the
compiler, and schema rules for e.g. <view> would be derived from
reading the appropriate LFC source file.
jim
