On 03.09.2011 22:53, Allen Wirfs-Brock wrote:
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.
Ah, come ooooon! >_* Are we here talking about a "coolness"?
Seems we started from the beginning that we have some _problems_ that:
(1) `toString` is not standardized and (2) a consequence from (1) --
some engines removes some code-parts from sources at toString
representation. We started the thread that we have the _issue_ of the
topic and that even though we may use some _hacks_ for such _toy ad-hoc_
implementations, still these implementations are nevertheless stay
_toys_ -- as a quick prototype -- to show a proposed feature. We started
from that it would be great to have such a thing available at _lower_ level.
We also said that _exact syntax_ and similar "coolness" is not a main
part of the proposal. That the ability to have the thing _embedded_ and
to get the help in the _consistent_ way -- is the main part.
From all this, I'd already better propose to standardize then
`toString` of functions. _Then_ you may organize some "competitions" or
a "cool" syntax in a "JavaScript derived" way. But this is completely
different story. However, even from this viewpoint it's more practical
to chose the solution which is here for years -- i.e. the syntax of
JavaDocs, which, once again, will turn-on the documentation for tones of
old code.
If the `toString` will be standardized, we may easily implement the
solution as a runtime library (though, good bye documenting of
built-ins!). If not, the only consistent and efficient behavior -- is to
have it as a pre-processor and to inject the doc-comment to AST for
function declarations.
May I at least ask, whether it makes sense to talk about `toString`
standardization? (because unfortunately this topic doesn't move forward
as I see -- don't want to have the docs for built-ins? -- as you wish, I
just proposed; though, ES don't even have a big standard library to
provide a detailed built-in documentation).
(don't get me wrong, I'm just trying to clarify the main goal of the
proposal; and for a library, standardizing of `toString` would be enough
and we may just close the topic)
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.
Yes, for a runtime library seems an elegant solution. Though, again, it
will be hard to force people just stop using the doc-style they are used
to use and to switch them to package-description style in a "JSON"
format. Though, I agree that this version looks nice. But, again -- the
original proposal wasn't about it, because we _had_ (before starting the
topic) working hacks that the runtime lib "just works". But nobody needs
hacks. Everybody wants a convenient documentation syntax for which there
are already many parser of the auto-docs generations.
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.
So, can we just standardize `toString` instead?
Dmitry.
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
es-discuss@mozilla.org
https://mail.mozilla.org/listinfo/es-discuss
_______________________________________________
es-discuss mailing list
es-discuss@mozilla.org
https://mail.mozilla.org/listinfo/es-discuss
