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:
![Hopefully not deceiving sketch.](/uploads/3f9e65a0dc091904e8267e23e58e37be/field_level_doc.png)
--
https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/38