Sure. If we take the hand-authored-js2doc approach, we could simply
add the APIs or LzBrowser et al to that document and just add a
feature to ignore certain source files in the compilation process.
On Mar 23, 2007, at 6:01 PM, Max Carlson wrote:
Really, these could be considered part of the kernel API, even
though they're not living there. So, this issue and the issue of
how to have canonical kernel API documentation are one and the same.
Of the options you've mentioned, I prefer the tag that says 'this
runtime is the canonical version.' Then, once we get the
documentation right for one runtime, we can generate the js2doc and
optionally shut off the doc build for that runtime if we want to
maintain the .js2doc manually.
What do you think?
Jim Grandy wrote:
Max,
One thing that I didn't anticipate in the refguide was the use of
the "platform" subdirectories to provide runtime-specific
implementations of non-kernel APIs. The upshot is that things like
LzBrowser which have implementations in both Flash and DHTML
appear *twice* in the Reference Guide. (It's true that kernel
classes appear once per runtime in the Contributor's Guide as
well, but that's less of a concern.)
The reason this is a significant problem is that files like swf/
LzBrowser.as and dhtml/LzBrowser.js were cloned from a single
original file, so they both contain reference comments. But the
comments are now quite diverged -- in the case of LzBrowser, the
swf version has a much better writeup than the dhtml version.
I suppose I could add sort of mechanism to merge documentation for
complementary implementations of the same class, but that doesn't
sound like fun. I guess the cleanest thing would be to push the
runtime designation down into the class' properties and methods,
perform a merge of the documentation for the two classes, and then
merge properties/methods with the same signature but different
runtimes, with some sort of heuristic for how to pick the winning
comments.
That sounds like a Master's thesis to me... Another way of doing
it would be to add a new tag that would say: ignore any other
implementations of this class, pretend this one works for every
runtime, and display the documentation as given here. So basically
you'd be saying that, e.g. the SWF version of LzBrowser, was the
canonical implementation, and all others should be ignored within
the refguide.
Still not entirely without problems, but simpler.
Any other options spring to mind?
jim
--
Regards,
Max Carlson
OpenLaszlo.org
