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
