Well, you couldn't do that because the class' footprint may be larger
than the interface's.
When you implement a method declared in a ES4 interface, do you have
to mark it 'override'? That would make it fairly easy to distinguish
between methods implementing an interface and new ones. Otherwise I'd
have to do more work.
jim
On Mar 26, 2007, at 9:18 AM, P T Withington wrote:
How about writing the doc on an interface and ignoring the doc on
classes that implement an interface?
On 2007-03-24, at 01:03 EDT, Jim Grandy wrote:
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
