i#4856: Add Doxygen links for instr_t and fix formatting

[AnandRaj2224]

This PR adds explicit # Doxygen links for instr_t in various header files, as discussed in issue #4856.

Fixes #4856

[AnandRaj2224]

@derekbruening ,I'm having trouble resolving the CI formatting failures on this PR.
I've tried running clang-format on the changed files, but the checks are still failing.

Could you please point me to the exact formatting command or script the project uses? I seem to be missing a step and would appreciate your guidance.

Thanks for your help!

[derekbruening]

@derekbruening ,I'm having trouble resolving the CI formatting failures on this PR. I've tried running clang-format on the changed files, but the checks are still failing.

Could you please point me to the exact formatting command or script the project uses? I seem to be missing a step and would appreciate your guidance.

https://dynamorio.org/page_code_style.html#autotoc_md123

https://github.com/DynamoRIO/dynamorio/blob/master/.github/workflows/ci-clang-format.yml#L82

[AnandRaj2224]

@derekbruening all the formatting checks (ci-clang-format, etc.) are passing now after rebasing onto the latest master and ensuring the correct clang-format-14 version was used for the header files. Thanks for the guidance!

However, there's one remaining failure in the ci-x86 / test (ubuntu-22.04, x86_64, RelWithDebInfo) job (ID: 53988260379).

Looking at the logs for that job, the errors seem related to the build environment itself:

Cross-compiler aarch64-linux-gnu-gcc not found,Cross-compiler riscv64-linux-gnu-gcc not found

Since my changes in this PR were only focused on fixing Doxygen @ref links for instr_t within comment blocks in .h files, these cross-compilation and build tool errors seem unlikely to be caused by my code changes.
I tried re-running the failed job, but the result was the same.
Could this be a temporary issue with the CI runner setup, or is there something specific I need to address in the configuration related to these cross-compilers?

Could someone please take a look or advise on how to proceed?
Thanks!

[derekbruening]

@derekbruening all the formatting checks (ci-clang-format, etc.) are passing now after rebasing onto the latest master and ensuring the correct clang-format-14 version was used for the header files. Thanks for the guidance!

However, there's one remaining failure in the ci-x86 / test (ubuntu-22.04, x86_64, RelWithDebInfo) job (ID: 53988260379).

Looking at the logs for that job, the errors seem related to the build environment itself:

Cross-compiler aarch64-linux-gnu-gcc not found,Cross-compiler riscv64-linux-gnu-gcc not found

Since my changes in this PR were only focused on fixing Doxygen @ref links for instr_t within comment blocks in .h files, these cross-compilation and build tool errors seem unlikely to be caused by my code changes. I tried re-running the failed job, but the result was the same. Could this be a temporary issue with the CI runner setup, or is there something specific I need to address in the configuration related to these cross-compilers?

Could someone please take a look or advise on how to proceed? Thanks!

The cross compiler is not an issue: that is just how the scripts operate, attempting various configs. The errors are the test failures at the very bottom:

2025-10-29T15:34:41.8631268Z ====> FAILURE in debug-internal-64 <====
2025-10-29T15:34:41.8631963Z debug-internal-64: 558 tests passed, **** 7 tests failed, of which 1 were flaky, but ignoring 2 for i#2941: ****
2025-10-29T15:34:41.8633205Z 	code_api|client.drx-scattergather 
2025-10-29T15:34:41.8633598Z 	code_api|client.drx-scattergather-bbdup 
2025-10-29T15:34:41.8634303Z 	code_api|sample.memval_simple_scattergather 
2025-10-29T15:34:41.8634651Z 	code_api|tool.drcachesim.scattergather-x86 

That is #7678 which is a regression that appeared recently and shows up occasionally but no one has been able to reproduce locally or root cause it, unfortunately. I tried a re-run of that job.

[derekbruening]

Please reply to all comments and mark resolved, per https://dynamorio.org/page_code_reviews.html#autotoc_md118, and then click the arrows to re-request a review.

[derekbruening]

@AnandRaj2224 AnandRaj2224 force-pushed the fix-doxygen-links-4856 branch 2 times, most recently from 9267dd3 to 2e247fc
2 days ago

Please do not force-push to a shared branch: it breaks the history and makes it hard to review. Seeing changes since the last review becomes impossible; comments lose their anchors in the code. Not doing force-pushes is documented in multiple places: https://dynamorio.org/page_code_reviews.html#sec_code_review_non_member, https://dynamorio.org/page_code_reviews.html#autotoc_md118.

The final merge squashes all the commits and the description comes from the PR text box: so there is no upside to a force-push and many significant downsides.

[AnandRaj2224]

@derekbruening,Thanks again for the review and clarifying the formatting issues. I really appreciate your guidance and patience as I learn the contribution process.

Regarding the specific formatting changes you pointed out (like the multi-line split for WINDOW_SUBDIR_FORMAT): You were absolutely right. My previous attempts at formatting were incorrect. To fix this properly, I followed the CI setup precisely:
Used Docker with an ubuntu:22.04 image.

Installed clang-format-14 using the exact repository source specified in the ci-clang-format.yml workflow.

Ran clang-format-14 -i on all the files I had modified.

This process did fix the incorrect multi-line splits you identified.

However, I observed that this correct run of clang-format-14 also removed all the # symbols I had manually added before instr_t in the Doxygen comments (which was the original purpose of this PR, addressing #4856).

Before I push the new commit containing these formatting changes (which does pass the CI checks but removes the # symbols), I wanted to ask for guidance:

what's the recommended way to handle the conflict with clang-format-14 ,Please let me know how you'd prefer to proceed.

[AnandRaj2224]

@derekbruening, I've pushed the final fixes for the formatting and the missing newline. All CI checks are passing now. Thanks again for all your help

[AnandRaj2224]

i have merged master to sync the branch. The new CI run is complete, and it looks like all the style errors are now fixed
The only remaining failures appear to be the known tests that you mentioned.

Thanks again for all your help and patience

[derekbruening]

LGTM. Thanks again for contributing!