Subject: Re: [Netconf] role of object description-stmt

From: Martin Bjorklund <[email-masked]>
Date: Tue, 01 Jun 2010 11:43:40 +0200 (CEST)

Andy Bierman <[email-masked]> wrote:
> So what to put in the description-stmts?

When we discussed this last time, I think we said that we should do as
for MIBs.  YANG modules will, just like MIBs, be extracted from the
RFCs and distributed by themselves, so it makes sense to make the
modules as self-contained as possible.

One extreme is netmod-types.  All normative text is specified in
description statements.  This works just fine for a module with
typedefs only.  In netconf-monitoring, the text provides a higher
level summary of the structure and descriptions in the YANG module.
ipfix does something similar; they describe the structure with
ascii-art UML diagrams.  In general, I think this is a good approach.

However, due to 4741 legacy, I agree that ietf-netconf.yang is
special.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Tue, 01 Jun 2010 09:05:22 -0700

> However, due to 4741 legacy, I agree that ietf-netconf.yang is

It isn't that special wrt/ IETF process.
A MIB module that instruments an IETF protocol
is usually in a separate document.  If not, the
normative text for the protocol is not in the MIB
DESCRIPTION clauses.

The same will be true for YANG modules.
A 'stand-alone' module like ietf-netconf-monitoring is
more likely to be the corner-case in the IETF.

The description-stmt is needed as a label that can be translated
into different languages.

(just making sure -- everywhere that YANG allows a description-stmt,
a reference-stmt is also allowed?  IMO we should use reference-stmt
instead of replicating any text outside the YANG module.)

> /martin

Andy