__doc__ for functions, classes, objects etc.

[Dmitry Soshnikov]

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 at mozilla.org
> https://mail.mozilla.org/listinfo/es-discuss

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.mozilla.org/pipermail/es-discuss/attachments/20110907/3a287ee1/attachment-0001.html>