Andrew Brown <atatat@atatdot.net> writes:

> putting anywhere that's not local to the code itself makes the
> maintenance problem about an order of magnitude harder as is evidenced
> by the fact that the documentation is not complete.  or, to put it the
> other way around, putting the "documentation" next to the code makes
> it easier.

I agree with John. The fact that it's harder - even your claimed
"order of magnitude" harder - to keep the documentation up-to-date
when it's in a separate place is not by far sufficent justification
for having the resulting documentation end up in kernel memory. That's
a high bar, and you haven't met it.

> that said, unless you want to write a program that will scan the
> *entire kernel source tree* looking for notes like these and determine
> which ones are relevant (ie, the machdep subtree has different stuff
> on every port), having them actually live in the tree so that they can
> be queried ad hoc also makes more sense.  rely on the linker and the
> kernel to find them automagically -- don't make work where you don't
> need to.

If you want to make the linker do the work, consider having the
relevant text end up in a section that is not normally loaded. Or read
up on "literate programming" tools.

        - Nathan