bneradt commented on code in PR #13112: URL: https://github.com/apache/trafficserver/pull/13112#discussion_r3120862941
########## AGENTS.md: ########## @@ -308,6 +308,38 @@ SMDebug(dbg_ctl, "Processing request for URL: %s", url); - UPPER_CASE for macros and constants: `HTTP_SM_SET_DEFAULT_HANDLER` - Private member variables have the `m_` prefix. +**Doxygen Comments:** + +When adding doxygen comments: + +- `@brief` is assumed for the first sentence, so give a brief summary right + after `/** ` without using `@brief`. +- In the description of classes, functions, and member variables, convey the + responsibility of the item being described (its role and intent), not just + what the code obviously does. +- Use `@a <name>` to reference a function argument by name in prose + (e.g. "If @a size is zero..."). Use `@c <text>` for inline code or + constants (e.g. `@c true`, `@c NULL`, `@c MyEnum::VALUE`). Review Comment: Yes, it can be overdone. Let's move forward with this - it should be an improvement on AI behavior over the current state of things. We can add some more direction later if we see it making an unreasonable amount of decorations. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
