Generate documentation comments

I have a set of public API functions in src/rendering/material.h that other teams will call. Generate documentation comments above each function and struct that explain what the caller must provide, the function’s side effects, and any performance characteristics (allocation, locking, expected complexity). Use short imperative sentences, mention thread-safety explicitly, and give an example of typical input for each function. Ladder L1

Before I commit these comments, make them easy for a graphics engineer reviewing a release note: surface the return value and error conditions first, make threading guarantees and ownership transfer unmistakable, and flag any parameters that are likely to be misused. Keep comments concise so they fit on a small popup in IDE tooltips. Ladder L2

I just changed the doc comments for TextureHandle and some callers now assume ownership is transferred; the build checks failed because my wording is inconsistent. I'm worried the wrong teams will adopt the wrong convention. What's the most likely misunderstanding from my current phrasing, and how should I rewrite the key sentence to make ownership explicit? Ladder L5

Over several releases, our inline comments slowly stop matching actual ownership, thread-safety and error behavior. Where do we keep losing accuracy in our documentation, and what habit should we adopt to keep comments truthful? Recommend one short process change, one CI guard, and one example template for doc comments that developers can follow. Ladder L6