[yang-doctors] Yangdoctors early review of draft-ietf-teas-yang-l3-te-topo-16

[Per Andersson via Datatracker <[e-mail]>]

Reviewer: Per Andersson
Review result: Ready with Issues

Hi!

This is my YANG-Doctor Last-Call review of
draft-ietf-teas-yang-l3-te-topo-16. This draft contains four modules
which seem to be in good shape but still have a few issues and nits.


Summary:

This document defines a YANG data model for layer 3 traffic engineering
topologies.


Comments:

o The YANG tree diagram listing is in better shape since the last
  review. However, there is still a lot of repetition and long YANG tree
  diagrams in Sections 4.2.2, 4.2.3, 4.2.4, 4.2.5, 4.2.6, 4.2.7, and
  4.2.11. Suggest to summarize the additions and further explain the
  augments. For instance explain the different augments once, in a cut
  out, and the add where it is augmented. The sections would also
  benefit from some pruning and more explanation of the presented YANG
  tree diagram.

o Checking YANG models

  Using pyang --ietf --lint yields several of the following errors

      [e-mail]:416: error: grouping
      "te-packet-path-bandwidth" not found in module
      "ietf-te-packet-types"

      [e-mail]:345: error: grouping
      "te-packet-path-bandwidth" not found in module
      "ietf-te-packet-types"

  It was not possible to see what grouping this might have been in
  ietf-te-packet-types. There is no "te-packet-path-bandwidth" grouping
  in any revision of ietf-te-packet-types.yang.

  Using yanglint yields no additional errors or warnings.

o Checking example instance data

  Using yanglint the following error is raised when validating the
  example data in Appendix B

      libyang err : Grouping "te-packet-types:te-packet-link-bandwidth"
      referenced by a uses statement not found. (Path
      "/ietf-te-topology-packet:{augment='/nw:networks/nw:network/\
      nw:node/tet:te/tet:te-node-attributes/\
      tet:connectivity-matrices/tet:path-constraints/tet:te-bandwidth/\
      tet:technology'}/ietf-te-topology-packet:packet/\
      {uses='te-packet-types:te-packet-link-bandwidth'}".)


Nits:

o The previous review asked for consistency regarding "description" and
  "presence" statements. There are still some inconsistensies, e.g.
  variating starting on the same or following line after the keyword.
  Please ensure that the style is consistent throughout the models.
  Suggest that all "description" and "presence" strings start on the
  line after the keyword because that style is mostly used throughout
  the models.

o The when and augment expressions' arguments are sometimes misaligned
  if they line wrap and are concatenated. Suggest aligning the
  subsequent concatenated strings with the first one.

o Extra space before "supported." in the module description for
  ietf-te-topology-packet-state.yang.

o In Section 4.2, the sentence needs to add article (the) before base:

      This is an augmentation to base TE topology model.


--
Per