I've been working on the julia internals on and off when I get the time, for example, over at #28878.

One thing I've been finding is that I don't always get the benefit of the devdocs, as I tend to read the code and code comments as a first resort, and don't always find some of the great tidbits of information available in the devdocs. I've been finding that the relationship between devdocs and the code itself strangely disjointed. It's hard to put my finger on what the problem is exactly, but I thought I'd open an issue to see what other people think. Perhaps it's just me and my overuse of grep (actually, ag) to discover things in the src and base directories.

Personally I like the code itself and inline contextual comments to tell the story of how things are, rather than relying on documentation which is elsewhere. For example, I love @yuyichao's documentation of the GC, and I love @Keno's documentation of the static analyzer annotations. These two are some of the better documented parts of the internals, but having the static analyzer documentation in doc/src/devdoc/gc-sa.md meant I found it only by accident when browsing rather than just finding it in the source at src/support/analyzer_annotations.h.

This leaves me wondering how we can make the documentation of the internals a little more uniform and accessible. A very simple approach would be to link from the code comments to the devdocs where applicable. This would certainly help, but I feel some of the markdown devdocs could be embedded in — or next to — the code which would make working with the code itself (using simple tools like grep) simpler and more contextual. If we want to extract these and insert them into the generated devdocs that would be possible with an automated extraction tool, in the same way that we document packages.