Re: Specification links in code generated from WebIDL

On Fri, Feb 24, 2012 at 12:55 AM, Charles McCathieNevile
<chaals@opera.com>wrote:

> On Fri, 24 Feb 2012 00:46:23 +0100, Robin Berjon <robin@berjon.com> wrote:
>
>  Hi Stefan,
>>
>> On Feb 22, 2012, at 21:39 , Stefan Haustein wrote:
>>
>>> The HTML 5 Canvas spec (1) provides link targets of the form
>>>
>>> CONSTANT_PREFIX + interfaceName.toLowerCase() + "-" +
>>> operationName.toLowercase();
>>>
>>> This makes it quite easy to link to the relevant parts of the
>>> specification, for instance in IDEs and / or generated JavaDoc comments.
>>> Unfortunately, other specifications such as WebGL or TypedArrays do not
>>> follow this schema.
>>>
>>> Do you think it would make sense to support this link schema as a
>>> general recommendation in WebIDL?
>>>
>>
>> I'm not sure that WebIDL would be the best place to make this
>> recommendation,
>>
>
> Nor am I. But some character called Berjon, and a bloke called Caceres
> were talking up an API cookbook recently as the sort of place where such
> advice would probably fit well...


http://www.w3.org/community/scriptlib/2011/11/29/api-design-cookbook-by-robin-berjon/

>
>
>  but even if we had a good place the above does seem to be too simple.
>> Notably, you can have multiple partial interfaces with the same name,
>> overloaded operations, etc.
>>
>
> Yes. That said, something along these lines seems a good practice to the
> extent that it works... (i.e. don't expect it to be perfect or break other
> stuff trying to make it so, but if the cap does fit...)
>

There are cases of overloaded operations in the Canvas specification --
this is then just resolved in the text, e.g.
http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#dom-context-2d-createlineargradient

This seems to be "good enough" and avoids the overhead of including the
full signature in every label.


> cheers
>
> --
> Charles 'chaals' McCathieNevile  Opera Software, Standards Group
>    je parle français -- hablo español -- jeg kan litt norsk
> http://my.opera.com/chaals       Try Opera: http://www.opera.com
>