doc: fix doxygen links to threads in developer-notes.md #35206

pull pinheadmz wants to merge 1 commits into bitcoin:master from pinheadmz:doxygen-threads changing 11 files +31 −16

pinheadmz commented at 2:32 PM on May 4, 2026: member
The "threads" section of developer-notes.md has links to anchor tags in the code generated by doxygen. As far as I can tell this was introduced in #18645 and changes to this section of this document have continued the pattern. The problem is, the content at https://doxygen.bitcoincore.org gets re-rendered daily and those anchor tags are generated internally by doxygen, so they are all broken now.

This PR adds doxygen syntax \anchor XXXX comments in the code where functions that run in these threads are defined, and then those stable, human-readable anchor tags are applied to the links in the doc.

I have generated the doxygen output from this branch, hosted it on my own web server, and created a modified developer-notes.md with these anchor tags and my server as host for demonstration:

https://gist.github.com/pinheadmz/ed3dda7d3c8d589e3989040519190b84#threads

Just note when looking at this:
- main is at the bottom of the html page so it might not look right at first
- initload is a lambda inside AppInitMain so thats where doxygen renders the anchor
DrahtBot added the label Docs on May 4, 2026
DrahtBot commented at 2:33 PM on May 4, 2026: contributor


The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.



Reviews

See the guideline for information on the review process.

Type Reviewers

ACK ViniciusCestarii

Concept ACK rkrux

If your review is incorrectly listed, please copy-paste <code></code> into the comment that the bot should ignore.



Conflicts

Reviewers, this pull request conflicts with the following ones:
- #35182 (Replace libevent with our own HTTP and socket-handling implementation by pinheadmz)
- #35173 (util: shorten thread names to avoid Linux truncation by l0rinc)
- #34411 ([POC] Full Libevent removal by fanquake)
If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.
pinheadmz force-pushed on May 4, 2026
pinheadmz force-pushed on May 4, 2026
pinheadmz force-pushed on May 4, 2026
DrahtBot added the label CI failed on May 4, 2026
doc: fix doxygen links to threads in developer-notes.md ab432d52ab
pinheadmz force-pushed on May 4, 2026
ViniciusCestarii commented at 6:46 PM on May 4, 2026: contributor

ACK ab432d52ab2d9f201845617cb7967725aa08ae60

Verified that there are broken links and even some old links resolving to unintended symbols like HTTP worker threads (b-http_pool_x), which you fixed
in src/index/base.h:170 in ab432d52ab
```
 166 | @@ -167,6 +167,7 @@ class BaseIndex : public CValidationInterface
 167 |      /// Starts the initial sync process on a background thread.
 168 |      [[nodiscard]] bool StartBackgroundSync();
 169 |  
 170 | +    /// \anchor sync
```
rkrux commented at 8:26 AM on May 5, 2026:

In ab432d52ab2d9f201845617cb7967725aa08ae60 "doc: fix doxygen links to threads in developer-notes.md"

Might be a nit: these anchors must be unique across the entire project, though it is unique at the moment but calling it only sync seems a bit generic.

- /// \anchor sync + /// \anchor index_sync
in src/util/threadpool.h:60 in ab432d52ab
```
  56 | @@ -57,6 +57,7 @@ class ThreadPool
  57 |      bool m_interrupt GUARDED_BY(m_mutex){false};
  58 |      std::vector<std::thread> m_workers GUARDED_BY(m_mutex);
  59 |  
  60 | +    /// \anchor http_pool
```
rkrux commented at 8:36 AM on May 5, 2026:

In ab432d5 "doc: fix doxygen links to threads in developer-notes.md"

This is not entirely correct, I remember facing a dilemma when I raised #34769.

threadpool is the common thread pool whose only use case at the moment is the http pool. But with #31132 and #34400 coming up that will reuse this common thread pool, putting the http_pool anchor here will be incorrect. That's why I had linked it to the portion in the httpserver.

https://github.com/bitcoin/bitcoin/blob/c89c8ddbb3657c6b53991c16faaf00e923cbc852/src/httpserver.cpp#L77-L78

If the anchor is put here, then I believe the anchors to the other uses of the common thread pool would also need to be added here.
rkrux commented at 8:39 AM on May 5, 2026: contributor

Concept ACK ab432d52ab2d9f201845617cb7967725aa08ae60

+1 on hosting the updated Doxygen output in your web server, makes it easier to verify.

main is at the bottom of the html page so it might not look right at first

True, this is the same problem with the current http pool link here: https://doxygen.bitcoincore.org/httpserver_8cpp.html#a2ad0a49dc9b5e8117c0dee98c24187d8

Type	Reviewers
ACK	ViniciusCestarii
Concept ACK	rkrux

Contributors

Labels

Linked (view graph)

#18645 [doc] Update thread information in developer docs

doc: fix doxygen links to threads in developer-notes.md #35206

Reviews

Conflicts