Hi Martin, thanks for the review.
Martin Bjorklund <[email protected]> writes: > Hi, > > I have reviewed this document, and here are my comments. I have some > technical issues; apart from that I think this document is ready > for publication. > > I have also implemented this statement in pyang (see the branch > 'yang-metadata' in pyang's github). > > Technical issues: > > o The 'type' statement is optional in 'md:annotation', and if it is > not present, the type defaults to string. I think this is bad > design: I followed the example of RELAX NG where type of attributes needn't be specified - as opposed to elements. > > - it is not consistent with how 'type' is used in other > YANG statements (leaf, leaf-list, typedef). > > - it is not as clear for the reader as having an explicit > type. > > - it saves just a few characters in every annotation (and > annotations will be rare) so it is not worth it. > > I suggest making 'type' mandatory in 'md:annotation'. OK, I am not against making it mandatory, if it is the consensus. > > > o The type of the argument to 'md:annotation' is not specified. It > should be an "identifier" (as defined in 6020bis). Yes, I will add it to the description of the "extension" statement. > > > o Last paragraph of section 3 and the "description" in the > extension. > > The text says that semantics are defined "by other means". I > think the semantics should be defined in the > description/reference statements (by using links or inline text > doesn't matter). Kent argued that an extension definition in YANG cannot make an annotation part of the contract between the server and client: the client can ignore it, and so the fact that the extension is defined in a module advertised by the server isn't sufficient for the server to start using the annotation and expect the client to take it into account. Hence "by other means", which can be, e.g. a capability. > > > Editorial issues: > > o You may want to change the "inactive" example to something less > controversial. For example: Yes, I've also realized this. I just thought it might be good to show an example with a non-string type and haven't got a better idea yet. > > module example-comment { > namespace "http://example.org/example-comment";; > prefix "ein"; > import ietf-yang-metadata { > prefix "md"; > } > md:annotation comment { > type string; > description > "This annotation is used to attach a free-form comment to > any data node."; > } > } > > > o Update the copyright year to 2015. OK. Thanks, Lada > > > /martin > > _______________________________________________ > netmod mailing list > [email protected] > https://www.ietf.org/mailman/listinfo/netmod -- Ladislav Lhotka, CZ.NIC Labs PGP Key ID: E74E8C0C _______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
