[netmod] Comments on draft-lhotka-netmod-yang-markup-00

[Robert Wilton <[e-mail]>]

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