## Regarding general feedback for v2
I think that most of the feedback goes in the direction of shifting from explaining **what things are** (which can often be extracted from the data type and name of the field) to actually explaining **how they are used**.
Of course, these type of comments will be more coupled to the rest of the code, but I see now that they are more helpful (as long as we keep them updated).
I can extract the following concerete things:
* Explain the direction of containment relationships and directly refer to the field in the other type that is connected to it. * Explain where/when the fields/structs are initialized (unless it is obvious). * Explain where/when the fields are used (unless they are always used). * Explain how the type is stored (this can be done in the fields in charge of containment relationships). * Usually the last two are related to a level in the code: source, IR, or bytecode. They may also be related to specific shader models. * Note when a type is unique, i.e. instanced only once, like hlsl_ctx. * If a field has a non-trivial data type, assume that the reader can go to its definition and extract more information from it.