__doc__ for functions, classes, objects etc.

[Xavier MONTILLET]

What about a simple property?

readFile.documentation = {
    name: 'readFile',
    arguments: [
        {
            name: 'path',
            type: 'string'
        },
        {
            name: 'encoding',
            type: 'string',
            optionnal: true
        },
        {
            name: 'callback',
            type: 'function'
        }
    ],
    description: 'Reads a file and calls the provided callback with
the content of the file as first argument.'
};
function readFile( path, encoding/*?*/, callback ) {
    var length = arguments.length;
    if ( length <= 1 ) {
        throw new TypeError( );
    } else if ( length <= 2 ) {
        callback = encoding;
        encoding = 'utf-8';
    }
    // do some stuff
    console.log( path, encoding, callback );
}

And that would also work on objects:

var API = {
    documentation: {
        name: 'API',
        properties: [
            {
                name: 'url',
                type: 'string',
                description: 'The current url.';
            },
            {
                name: 'goToGoogle',
                type: 'function',
                description: 'Change current url to Google.'
            }
        ]
    },
    url: '',
    goToGoogle: function ( ) {
        this.url = 'http://www.google.com/';
    }
};

On Mon, Sep 5, 2011 at 5:40 PM, Andreas Rossberg <rossberg at google.com> wrote:
> On 5 September 2011 16:12, Dmitry
> Soshnikov <dmitry.soshnikov at gmail.com> wrote:
>>
>> On 05.09.2011 13:26, Andreas Rossberg wrote:
>>
>> I am indifferent about the general idea of a doc interface,
>>
>> Then I don't think incorrect judging about the concept of an "abstraction"
>> is a good topic in this thread (you may open a new one). Abstraction is
>> about _abstraction_, it's not about "security". Especially in the
>> interpreted dynamically typed language with embedded reflection.
>> Abstractions are for programmers. Not for "hackers".
>
> Well, properly maintaining language-level abstractions is a prerequisite for
> security, but security is by no means the only reason to want abstraction.
> Reliability and modularity are others (and the ones that I personally care
> about even more). In any case, I don't think you want to introduce or bless
> another feature that interferes badly with either of these concerns -- it's
> almost guaranteed to lead to legacy that will cause a big headache later.
>
>>
>> but: having to peek at the _implementation_ of something (which is what
>> toString does) in order to gather its _interface_ description sounds like a
>> fundamental violation of basic principles and exactly the wrong way to go
>> about it.
>>
>> Fundamental principle of an abstraction, once again, is _the abstraction_.
>> That is, to provide convenient black box with API hiding implementation
>> details.
>
> I was specifically referring to the separation of interface and
> implementation. Documentation is interface description, intended to avoid
> having to look at the implementation. Wouldn't it be ironic if the mandatory
> way to get to it was by looking at the implementation?
> /Andreas
>
> _______________________________________________
> es-discuss mailing list
> es-discuss at mozilla.org
> https://mail.mozilla.org/listinfo/es-discuss
>
>