Add doxygen comments to DiagsTypes.hh

[JosiahWI]

I am testing out Claude Sonnet 4.6 and Claude Opus 4.7 with spec-kit. This change was generated by those models. Since code comments are very tedious to write by hand (especially for pre-existing code) and can provide great benefit, I think this is a good use case for experimentation. If this is accepted, I might do more of these as I refine my spec-kit configuration.

[Copilot]

Pull request overview

This PR adds Doxygen (“oxygen”) comments to ATS’s diagnostics and regression-test interfaces to make the Diags subsystem’s behavior easier to understand and navigate from headers.

Changes:

• Adds API-level documentation for tell_diags_regression_testing_is_on() in Regression.h.
• Adds extensive Doxygen comments across DiagsTypes.h for Diags configuration, tag activation, output routing, and log rolling/redirection APIs.
• Adds documentation for the global Diags singleton registration/access in Diags.h.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 13 comments.

File	Description
include/tscore/Regression.h	Documents regression-mode diags behavior.
include/tscore/DiagsTypes.h	Adds Doxygen comments for Diags types, fields, and public APIs.
include/tscore/Diags.h	Documents DiagsPtr::set() and diags() singleton accessor.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 8 comments.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 20 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

include/tscore/DiagsTypes.h:611

• activate_taglist()’s Thread safety note says it “Acquires tag_table_lock”, but the implementation only takes the lock when @a taglist is non-null (to swap activated_tags[mode]). When @a taglist is nullptr and @a mode is DiagsTagType_Action (or non-global debug), no lock is taken. Tighten the wording so it matches the actual locking behavior.

   * @par Thread safety
   * Acquires tag_table_lock. Safe to call concurrently with
   *   emission, but serialized with other reconfiguration methods.

include/tscore/DiagsTypes.h:125

• The DiagsCleanupFunc documentation describes DL_Fatal/DL_Alert as exiting via a “recoverable path”. The implementation uses ink_fatal_va() which unconditionally terminates the process via _exit(70); nothing is actually “recoverable”. Consider documenting the concrete exit statuses instead (UNRECOVERABLE_EXIT vs 70) to avoid implying the process continues.

This issue also appears on line 609 of the same file.

 * @post On return, the process is terminated; control does not return to
 *   the emitter. DL_Emergency exits via the unrecoverable path; DL_Fatal
 *   and DL_Alert exit via the recoverable path.

[JosiahWI]

Out of scope and won't fix here, but might be a bug.