When reading the source by clicking the Source button I often find the source hidden by "magic". For example looking at setLen in the system module this is the source shown:
proc setLen*(s: var string, newlen: Natural) {.
magic: "SetLengthStr", noSideEffect.}
magic symbols are implemented in the compiler, the show source is actually correctly pointing to the declaration in https://github.com/nim-lang/Nim/blob/devel/lib/system.nim#L962
it's not 100% clear how to improve this further to make docgen more useful for people exploring compiler code. Maybe making docgen turn automatically magic: SetLengthStr into a hyperlink pointing to where mSetLengthStr is declared, since it's a common gotcha
I don't see how that would help. But then I don't see why compiler builtins are confusing either. It's not turtles all the way down, there is a ground floor.
One of my favorite metaphors :) But it's not really a ground floor, it's more like the turtles are standing on dinosaurs (C code), which are standing on trilobites (assembly code)...