Thoughts on weaving variable documentation

[Grant Rettke <gcr@wisdomandwonder.com>]

Good morning,

A lot of people are weaving their Emacs init files for the obvious
reason: it is difficult to remember why
we configured stuff and other people definitely won't know why we did
it. There is a common operation
that occurs though when other people read our Emacs init:

1. They open it up in Emacs
2. Find what looks interesting
3. Do a C-h f or C-h v on it and learn about it

Makes total sense.

What I got curious about is for this specific use case, people
scanning other people's configs, how I
could make it easier. A thought is to weave the docstrings for
variables right into the weaved file any
time a variable is set. I am thinking something like this:

1. When the weave occurs
2. Look at each line of code that starts with a setq
3. Look up the docstring for the variable
4. TBD: Weave that documentation into the output.

That is the idea, at least.

My question is:
1. What are the standard mechanisms to do something like this within
the ob lifecycle?
2. What do you think in general?

Kind regards,

Grant Rettke | ACM, ASA, FSF, IEEE, SIAM
gcr@wisdomandwonder.com | http://www.wisdomandwonder.com/
“Wisdom begins in wonder.” --Socrates
((λ (x) (x x)) (λ (x) (x x)))
“Life has become immeasurably better since I have been forced to stop
taking it seriously.” --Thompson