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 <rossb...@google.com> wrote:
> On 5 September 2011 16:12, Dmitry
> Soshnikov <dmitry.soshni...@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@mozilla.org
> https://mail.mozilla.org/listinfo/es-discuss
>
>
_______________________________________________
es-discuss mailing list
es-discuss@mozilla.org
https://mail.mozilla.org/listinfo/es-discuss
