[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: snmpconf comments should never include technical descriptions



HI,

once again...

>Date: Tue, 13 Mar 2001 10:54:46 -0800
>To: snmpconf@snmp.com
>From: "David T. Perkins" <dperkins@dsperkins.com>
>Subject: Re: snmpconf comments should never include technical
>  descriptions 
>In-Reply-To: <200103131522.KAA11136@europa-h0001027441c5.ne.mediaone.net
> >
>References: <Your message of 09 Mar 2001 14:05:04 -0800. <sd1ys6lhtb.fsf@wanderer.hardakers.net>
>Mime-Version: 1.0
>Content-Type: text/plain; charset="us-ascii"
>
>HI,
>
>One approach that I use is to use the DESCRIPTION clause of the
>MODULE-IDENTITY construct to describe the MIB module and list
>abbreviations that the MIB module reader would find useful.
>The text to put in the RFC before a MIB module is background
>and explanations. It is for the reader that has not yet read
>the MIB module. The content of the MIB module is really a
>reference for people that have already read the document (RFC),
>and assumes that the background concepts are understood.
>That is, all the text in an RFC before a MIB module MUST not
>be moved to the DESCRIPTION clause of the MODULE-IDENTITY!
>
>Regards,
>/david t. perkins
>
>At 10:22 AM 3/13/2001 -0500, Jon Saperia wrote:
>>Wes
>>> 
>>> Ok, this is, then, a separate message on the subject.
>>
>>>From what you wrote below, I think we are in essential agreement and
>>Mike and Wayne and I can include text that carries your suggestion in
>>what I hope will be the final revision after the IETF.  One other item
>>that should be added though is that there is value in the front matter
>>of both standard and vendor specific MIB Modules that gives general
>>contextual or technology grounding for the MIB Module. I do not think
>>this violates your rules about putting things in the DESCRIPTION clause
>>though.
>>
>>thanks
>>/jon
>>> 
>>> IMHO, it is very bad practice to describe how an object or group of
>>> objects is supposed to behave, why it is in existence, etc, outside of
>>> the description clause for that object or group of objects.  Comments,
>>> specifically, should never be used to document an object in any way.
>>> Something like:
>>> 
>>> 
>>> 
>>> Proper and Improper use of MIB comments
>>> 
>>>   Comments within MIBs are started with two '-' symbols: "--".
>>>   Comments are ignored by any tools which systematically parse a MIB
>>>   definition in order to extract some set of information from it.
>>>   Because of this, it is extremely important that comments not be used
>>>   to describe how an object or group of objects is supposed to behave,
>>>   why they exist.  More generally, comments should not be used as a
>>>   form of documentation.  The proper place for documentation is in the
>>>   DESCRIPTION clause of an appropriate object.
>>> 
>>>   Comments are not without merit, however.  They can be used to
>>>   provide a separator between large sections of the mib, such as:
>>> 
>>>     --
>>>     -- Begin Acme notification objects
>>>     --
>>> 
>>>   They can also provide a place for MIB authors to comment on sections
>>>   that need to be fixed, or to document problems with an object.
>>>   Typically, though, these types of comments would be removed before
>>>   external publication.
>>> 
>>>   In short, if you're unsure of where to put text, put it in a
>>>   description clause not in a comment.
>>> 
>>
>>> 
>>
>>Thanks,
>>/jon
>>--
>>
>>Jon Saperia                  saperia@jdscons.com
>>                             Phone: 617-744-1079
>>                             Fax:   617-249-0874
>>                             http://www.jdscons.com/