Re: ReSpec IDL: how to add comments inside an IDL block, and specify that "Class1 implements Class2" outside the block

On 08/03/2013, at 11:37 PM, James Craig <jcraig@apple.com> wrote:

> I never saw an answer to this, so I'm resending.
> 
> On Dec 3, 2012, at 10:53 AM, James Craig <jcraig@apple.com> wrote:
> 
>> On Dec 3, 2012, at 8:41 AM, Robin Berjon <robin@w3.org> wrote:
>> 
>>> On 03/12/2012 17:29 , James Craig wrote:
>>>> I've read the ReSpec.js docs and examples, and it mentions that some
>>>> aspects of WebIDL are supported in ReSpec, but it's not clear to me
>>>> which are not, or how to include some aspects, specifically these two:
>>>> 
>>>> interface Foo {
>>>>    // 1. comments inside an IDL interface block
>>>> };
>>>> // 2. and any additional lines outside of an interface block such as:
>>>> Foo implements Bar;
>>>> 
>>> 
>>> Neither is supported, and neither will ever likely be with the current IDL setup (the module for which is called webidl-oldschool for a reason).
>>> 
>>> By popular demand, I'm considering adding a *completely* new mode of entering IDL. It will involve just typing WebIDL and using hot comments to generate the description (which will also be less verbose). Comments that aren't hot comments will just get copied to the output.
>> 
>> Why rewrite completely instead of just adding a a few classes for the DT elements, potentially like the following possibilities…
>> 
>> <dl class="idl" title="interface Foo">
>> 
>> <!-- reserved 'comment' member -->
>>    <dt class="comment">A comment about the LOREM constant</dt>
>>    <dd></dd>
>>    <dt>const unsigned short LOREM = 1</dt>
>>    <dd>Lorem ipsum…</dd>
>> 
>> <!-- @title or @data-comment attribute on member -->
>>    <dt data-comment="A comment about the IPSUM constant">const unsigned short IPSUM = 2</dt>
>>    <dd>Lorem ipsum…</dd>
>> 
>> <!-- implementation declarations outside the block -->
>>    <dt class="implements">Foo implements Bar</dt>
>>    <dd></dd>
>>    <dt class="implements" data-comment="Comment about Foo implementing Baz">Foo implements Baz</dt>
>>    <dd></dd>
>> 
>> </dl>
>> 

I don't think we should do what you a proposing as, in the case of comments,  it would result in invalid WebIDL. This would cause issues when automatically scraping specs for WebIDL for generating tests or simple validating the IDL with a WebIDL parser. 

Also, I think it's better to keep WebIDL statements, such as x implements y;, separate in the spec. Even though the statement is short, it has significant implementation consequences - so warrants its own section forcing the Editor(s) to explain why the interface implements instead of extends. Thus, it is best to keep them in their own sections.

Hope that helps!

Received on Saturday, 9 March 2013 08:59:54 UTC