__doc__ for functions, classes, objects etc.

[Allen Wirfs-Brock]

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


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