Subject: Re: [netmod] yang-02 examples nits

From: Andy Bierman <[email-masked]>
Date: Tue, 02 Dec 2008 08:19:05 -0800

Phil Shafer wrote:
> Andy Bierman writes:
>>  1) pg 91.: augment example uses type ChannelNumber, which is not
>>     defined anywhere
> 
> Given that examples are not meant to be fully self-contained, I'm
> not sure I see an issue here.  ChannelNumber may be defined elsewhere
> in the module, not all of which is included in the example.
> 

Most of them are self-contained, or they reference previous
examples.  Somebody might think ChannelNumber is a builtin type,
because they are the only types that get used without any
associated YANG definition.

>>  2) sec. 9.4.5: 2nd and 3rd constructs should be legal YANG.
>>     The type clause cannot appear alone, and this example is confusing.
> 
> This type clause can appear inside a leaf or a typedef.  The examples
> aren't meant to be self-contained, so the enclosing statements are
> not included.
> 

The examples need to be self-explanatory.
As a co-author, you have no idea how many details
your brain is filling in (correctly) for each example.
For somebody looking at the spec the very first time,
the details will likely get filled in differently.

How about a short sentence before the 2 'type' statements:

    Another typedef or a leaf statement may refine the previous
    typedef range statement. For example:

>>  3) sec. 9.6.5: it would be good to show an enumeration example
>>     that has complex identifiers, to point out how different
>>     they are from bit names.
>>     typedef my-display-duplex {
>>         type enumeration {
>>             enum 'half duplex';
>>             enum 'full duplex';
>>             enum 'unknown duplex';
>>         }
>>     }
> 
> If we need this, we should use a better example, since
> <duplex>half</duplex> is a better encoding.  Personally I think
> this (the ability of a enum to contain a space) is a minor point
> nor worthy of an example.
> 

Fine -- pick a better example.  Show just 1 enum with quotes.
I think that some developers will miss this important
detail and not allow 'inside' whitespace.

> Thanks,
>  Phil

Andy

_______________________________________________
netmod mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/netmod