I believe this information could be very useful for newcomers to the HLSL compiler.
Documentation often needs to reference other parts of the code, so it can be a problem to update these references if the referenced code is modified. However, I think that documentation in the data definitions (as opposed to documentation inside the functions) is easier to maintain, since each data type is declared in a single place, to which one often keeps going back for reference, so it is less probable to forget to update a comment.
Also, it opens up the possibility of explaining **what** things are, instead of **how they are used**, in some cases, avoiding these references to other places in the code.
I can think on the following additional benefits:
* Updates in these documentation comments, when the way a field is used changes, or when new fields are added, can help making future commits more readable. * Some IDEs display the comments above the field/struct declaration when the cursor is over an use of this field/struct.
A hopefully not deceiving sketch:
