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
