Brian's potted lecture on program documentation:
A program is a tree structure. It has some big tasks to carry out (parsing user input, say). The big tasks have medium-size constituent tasks, etc. Each of these tasks is carried out by a family of procedures.
So in a perfect world, in which programmers had liberal educations and knew how to write, there would be a documentation tree isomorphic to the program tree. There would be a Program Logic Manual describing the overall structure of the program. (That's what they were called at IBM when I was a child; they were themselves products IBM would sell you.) Then there would be more detailed documentation on the intermediate program chunks, or at least on the interesting ones. (If a chunk did something really new, or did it in a really new way, such intermediate documentation might include a journal article to announce the new thing to the world. Think about the Mapreduce article as a paradigmatic example.) And then, out at the leaves of the documentation tree, there would be inline comments attached to the code of each procedure.
So, it isn't a perfect world, and programmers would much rather program than write documentation. So you're lucky if you get user documentation, let alone internal documentation.
Given that state of affairs, if you (the later maintainer of a program, your own or someone else's) can only have a subset of the complete documentation tree, which subset would you like? I claim that you want the top levels of the tree, documenting the overall program and its major components. If you understand those levels, you can read the code, which should be largely self-documenting anyway. But, alas, what you get instead is the very bottom level of the documentation tree, the inline comments per procedure, which are almost always a direct translation of the code into English. (Yes, I know there are other human languages, but not so much in the computing world. When I visited China, a week after Mao died, the only person I met who spoke English other than the professional interpreters was the head of a university CS department.) Those inline comments rarely give me any insight into the code, my own or someone else's.
So, for example, in Snap!, we don't really have separate internal documentation, but what we do have is the great big comment at the beginning of morphic.js, and that's what you really want to read, to understand how Snap! works. The inline comments are less useful, imho. (There is also some intermediate-level documentation in the form of large comments at the beginning of the implementation of an object class.)
I'm an extremist about this. I tell my students that any time I'm tempted to put a comment in my code, I take that as a sign that I'm being too clever and should instead rewrite the code to be understandable. (Really, this is true; when I revisit my own code years later, and there's a comment, the code gives me a headache and the comment doesn't help a bit.)
The paradigmatic example of inline commenting is in Unix v6, the first one to be distributed outside of Bell Labs. In the scheduler, the switch from one user process to another is done in one instruction, which just assigns a new value to the hardware register containing the stack pointer. And the comment is
// You are not expected to understand this.
It's the only thing everyone still remembers from v6.
And you didn't really answer
Anyway, we already have the ability to attach comments to blocks, so there's no need for you to invent another way. And your program block is going to be gigantic even without the inline comments, if you imagine extending the grandmother example to a general family tree package.
Speaking of packages, I know you know this, because you said "in the current version," but what we need way more than inline comments are the ability to include a package of rules by reference, and an interactive REPL! (I want you to get it perfect, so that we can make this an official library and I don't have to write one!)