On 2007-03-26, at 12:59 EDT, Jim Grandy wrote:
Well, you couldn't do that because the class' footprint may be
larger than the interface's.
I suppose, but presumably those extra methods would be private, since
they are not part of the interface?
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.
Good question. I'll ask!
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
