[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: snmpconf comments should never include technical descriptions
>Date: Tue, 13 Mar 2001 10:54:46 -0800
>From: "David T. Perkins" <email@example.com>
>Subject: Re: snmpconf comments should never include technical
>References: <Your message of 09 Mar 2001 14:05:04 -0800. <firstname.lastname@example.org>
>Content-Type: text/plain; charset="us-ascii"
>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!
>/david t. perkins
>At 10:22 AM 3/13/2001 -0500, Jon Saperia wrote:
>>> 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
>>> 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.
>>Jon Saperia email@example.com
>> Phone: 617-744-1079
>> Fax: 617-249-0874