Hi Lada,
I've had a quick scan of your YANG markup extension draft and I have a
few comments:
Allowing description, and similar descriptive statements, to use
something other than text seems like it could be useful in some cases.
I'm not sure that allowing the statements to use any text-like media
type is a good idea, this could increase the burden on tool makers if
each module author chooses their own preferred format.
Instead, I think that it might be better to restrict it to a very small
set of media types, that could be extended in future. I would think
that initially just allowing plain text and one particular flavour of
markdown would be a reasonable starting point.
I think that the only formats that should be allowed are those that are
still readily readable as plain text, so that tools that don't want to
parse the formatted text can still sensibly display the descriptive
statements. I.e. I don't think that it would be helpful to allow things
like text/xml since it isn't easy to read.
Allowing this extension on particular descriptive statements may also be
helpful. It seems plausible that the vast majority of these statements
in a module might just be written in plain text with just a few of them
using more advanced formatting like markdown.
Finally, I have a concern that if more structured formatting in the
comments is used then would that encourage model writers to produce more
verbose comments, and if so that might possibly reduce the readability
of the modules. Although, I guess ultimately one has to trust the model
writers to do the right thing.
Thanks,
Rob
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
