On Sep 2, 2011, at 3:29 PM, Irakli Gozalishvili wrote:
>
> https://github.com/Gozala/doc
>
I want to second Brendan on the coolness of this. It really is a JavaScript
derived solution rather than simply copying what somebody else did for some
other language.
I have a couple of thoughts to throw in.
The documentation description doesn't need to be a single structured string.
It could also be something like:
function sum(x, y) {
doc: {
name: "sum";
parameters: {
x: "first value to sum"; expected: "Number";
y: "second value to sum"; expected: "Number";
}
returns: "Number";
description: "Compute the sum of two numbers";
docUrl: "http://maysite.com/myapp/designDoc.html#sum";;
}
return x + y;
}
This doc blocks looks something like an object literal but is really composed
of nested labelled blocks and statements. However, it would be pretty easy to
translate such a structure into a JSON object structure.
Whether a string or a structured labeled block is used, if we hope for multiple
tools and IDEs to support it then somebody needs to propose and promote a
specific documentation schema.
Oliver is correct that you can't depend upon Function.prototype.toString
actually reproduce such a structure, but it is a pretty good fallback source
for a runtime tool to try when it can't find the documentation anywhere else.
Earlier in this thread I was stressing that it is desirable to make it
impossible for application logic to have dependencies upon such metadata. This
approach satisfies that requirement. In fact, if this convention was
established I would expect minimizers to strip out any such documentation.
Given that you can't depend upon the documentation to be in the actual
downloaded source code runtime tools need a convention for finding the
documentation. I suggest above that such a documentation block could easily
be translated into JSON. Such a convention might be something like that given
a executed file located at "http:somepath/foo.js" or "http:somepath/foo.min.js"
the file "http:somepath/foo.js.doc.json" contains the documentation objects for
the file. Of source, someone needs to write a documentation extractor to
produce such files.
Allen
_______________________________________________
es-discuss mailing list
[email protected]
https://mail.mozilla.org/listinfo/es-discuss
