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

Re: snmpconf comments should never include technical descriptions

> 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		     saperia@jdscons.com
			     Phone: 617-744-1079
			     Fax:   617-249-0874