Re: section 4.6.2 of review-guidelines

["C. M. Heard" <heard@pobox.com>]

On Fri, 4 Jun 2004, Randy Presuhn wrote:
> > From: "Harrie Hazewinkel" <harrie@lisanza.net>
> > To: "Mreview (E-mail)" <mreview@ops.ietf.org>
> > Cc: "Harrie Hazewinkel" <harrie@lisanza.net>
> > Sent: Saturday, June 05, 2004 7:29 AM
> > Subject: section 4.6.2 of review-guidelines
> ...
> > The issue is that I sometimes have noticed that in the
> > DESCRPTION clause a textual equivalent of for instance the
> > DEFVAL-clause, or UNITS is given.
> > I personally dislike this, since it for of all MUST go
> > into a DEFVAL-clause or UNITS-clause and as a result
> > is redundant. Therfore, I beleive we should
> > add some text in section 4.6.2 regarding this.
> >
> > I understand it may be seen as a CLR, but then again
> > an editor simply creates himself more work by adding
> > the textual information that is/must be part in the
> > FORMAL clauses.
> ...
> 
> I think prohibiting redundancy in description clauses is
> going too far.  In the case of DEFVAL, it may in fact
> not really be redundancy, since the description could
> place stronger requirements on that default value than
> DEFVAL does.  Likewise, in the case of UNITS, the
> description may spell out accuracy / precision details
> that could not be inferred from the UNITS clause by
> itself.

I agree with Randy.  In many cases a REFERENCE clause will
just be a summary of more detailed information in the
DESCRIPTION clause.  Here is an example from the ETHER-WIS
MIB in RFC 3637:

etherWisDeviceTxTestPatternMode OBJECT-TYPE
    SYNTAX  INTEGER {
                none(1),
                squareWave(2),
                prbs31(3),
                mixedFrequency(4)
            }
    MAX-ACCESS  read-write
    STATUS  current
    DESCRIPTION
       "This variable controls the transmit test pattern mode.
       The value none(1) puts the the WIS transmit path into
       the normal operating mode.  The value squareWave(2) puts
       the WIS transmit path into the square wave test pattern
       mode described in [IEEE 802.3 Std.] subclause 50.3.8.1.
       The value prbs31(3) puts the WIS transmit path into the
       PRBS31 test pattern mode described in [IEEE 802.3 Std.]
       subclause 50.3.8.2.  The value mixedFrequency(4) puts the
       WIS transmit path into the mixed frequency test pattern
       mode described in [IEEE 802.3 Std.] subclause 50.3.8.3.
       Any attempt to set this object to a value other than
       none(1) when the corresponding instance of ifAdminStatus
       has the value up(1) MUST be rejected with the error
       inconsistentValue, and any attempt to set the corresponding
       instance of ifAdminStatus to the value up(1) when an
       instance of this object has a value other than none(1)
       MUST be rejected with the error inconsistentValue."
    REFERENCE
       "[IEEE 802.3 Std.], 50.3.8, WIS test pattern generator and
       checker, 45.2.2.6, 10G WIS control 2 register (2.7), and
       45.2.2.7.2, PRBS31 pattern testing ability (2.8.1)."
     ::= { etherWisDeviceEntry 1 }

One could argue that the REFERENCE clause (which is optional) is
should be omitted in this case because it's redundant.  However,
that's a matter of opinion;  some people considered it helpful
to have a summary listing of the IEEE 802.3AE reference clauses.

I think that the bese course of action would be to leave this
matter to the discretion of the author.  The reviewer is always
free to make suggestions about any stylistic matters that he or
she dislikes -- I've done that quite frequently -- but I don't
think we want to make that anything stronger than a suggestion.

Mike