On Fri Nov 11 09:50:15 2022 +0000, Francisco Casas wrote:
## 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.
I would add: explain what formal rules an object of a type must satisfy. E.g., when this flag is set this field is relevant, otherwise it's not; or when this field is set to this value, then this other field must be non-negative. As usual, taking with a grain of salt if the explanation becomes so convoluted that it doesn't really help.