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.
-- https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/38#note_14039