masaori335 commented on code in PR #13112:
URL: https://github.com/apache/trafficserver/pull/13112#discussion_r3120805666
##########
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:
Sometime, too many `@c` make me dizzy to read in text.
```
* Handles two transitions:
* - @c UP → @c DOWN: @c _last_failure is @c TS_TIME_ZERO; set via CAS.
* - @c SUSPECT → @c DOWN: @c fail_window has elapsed since the last
failure; @c _last_failure is
* refreshed via CAS to restart the fail window.
```
--
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]
