Subject: Re: [netmod] minor question - YANG Document Guidelines: Imports

From: Martin Bjorklund <[email-masked]>
Date: Tue, 02 Feb 2016 12:21:19 +0100 (CET)

Robert Wilton <[email-masked]> wrote:
> On 28/01/2016 20:01, Juergen Schoenwaelder wrote:
> > On Thu, Jan 28, 2016 at 01:57:22PM -0500, Joel M. Halpern wrote:
> >> I ran into something while reading a YANG internet-draft recently, and
> >> I
> >> wonder if a bit of advice in the YANG Document Guidelines (rfc6087bis)
> >> would be reasonable.
> >>
> >> Section 4.8 of the guidelines states that any imported modules must
> >> also
> >> have a reference in the references section.  Which is good.  But there
> >> is no obvious way for a human reader to relate the two.
> >>
> >> Would it be sensible to recommend in this document (I don't know if it
> >> would be 4.8 or a new section later in the document) that import
> >> statements have a comment with them either naming the internet draft /
> >> RFC they are importing from, or pointing to the reference which names
> >> it?
> >>
> > Perhaps RFC 6087bis can give additional guidelines. The common way to
> > get the references into the enclosing document is to include a
> > statement before the definitions that says something like:
> >
> >     This module imports <stuff> from the <foo-module> defined in
> >     [RFCXYZ] and <stuff> form the <bar-module> defined in [RFCABC].
> >
> > To help readers that have the module and who do not want to bother
> > looking up the document, including comments may help. It is kind of
> > funny that YANG does not allow reference statements on imports...
> It is too late to add this to Yang 1.1?
> 
> That would seem to be the cleanest solution.

It seems to me that allowing "reference" under "import" (and
"include") is a "safe" change, i.e., I support adding it even though
it is pretty late in the process.

One thing to note is that in the current grammar, "reference" and
"description" are always allowed together - does it make sense to
allow "description" in the import/include as well?

/martin

> 
> I was under the, possibly mistaken, assumption that various YANG tools
> effectively ignore/strip out the comments and hence comments are
> better embedded directly in the model as either reference or
> description statements.
> 
> Rob
> 
> 
> >
> > /js
> >
> 
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod
>

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 2 Feb 2016 12:27:32 +0100

> On 02 Feb 2016, at 12:21, Martin Bjorklund <[email-masked]> wrote:
> 

IMO, yes.

Lada

--
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: E74E8C0C

---

From: Robert Wilton <[email-masked]>
Date: Tue, 2 Feb 2016 11:39:34 +0000

> allow "description" in the import/include as well?

I would say yes.  I can't see that it would cause any harm, nor does it 
look like it would be particularly burdensome to implement.

E.g. it could be a useful way of documenting if an import was only 
required for a slightly more obscure reason.

In general it feels like documenting the YANG model using 
descriptions/references is probably better than comments which are 
likely to only be available in the YANG source file and then get 
stripped out during parsing.

Rob

> .