Re: CVS commit: src/sys/fs/tmpfs

["Perry E. Metzger" <perry%piermont.com@localhost>]

Jason Thorpe <thorpej%shagadelic.org@localhost> writes:
> On Sep 13, 2005, at 11:44 AM, Perry E. Metzger wrote:
>> I have to say I disagree. Often, in trying to debug one portion of the
>> kernel or another, it is VERY valuable to understand the inside of how
>> that portion of the kernel works. The 4.4 book is pretty old at this
>> point and was woefully incomplete.
>
> In this particular case, no other part of the kernel interacts with
> the code being documented.  It is only referenced in the context of
> itself.

Sure, but there will be times where people want to make changes and
fixes to that code itself.

>> Surely you don't think less documentation is better than more?
>
> I like more documentation.  But I think having a tmpfs(9) manual page
> is confusing to people who are looking for more information about
> kernel APIs, because tmpfs isn't one.  So put the documentation in
> the appropriate place, which in this case is a README in the
> directory that holds the tmpfs source code.

That could work. The only objection I have is it isn't
systematic. That's a very "Linux" way of doing things -- their sources
are littered with READMEs and no one ever knows where to find a
particular piece of information.

I have thought about this for a little bit and I've concluded that I
think the section 9 approach is fine. Here is why.

1) Generally, the man pages for non-APIs won't impede people finding
   APIs. That is, if I try "man gettodr" the fact that a tmpfs man
   page is in section 9 to doesn't hurt you. Similarly, the existence
   of API man pages doesn't interfere with finding/looking at the
   non-API pages. No real harm is caused by the convention, which I
   think is important.
2) Section 9 gives us a place to collect such information so it isn't
   scattered into a thousand READMEs.
3) Putting such things into the supplemental docs doesn't work for
   things that aren't full sized papers but just brief "orientation
   documents", so again, a man page seems correct.
4) It is really easy to get at a man page -- "man foo".

If you object strongly enough, we can come up with an alternative
scheme to section 9, but I'd urge that any such scheme

a) not consist of files scattered about without consistent style,
   formatting, location or name.
b) be easy for the user to explore. (see point 4)

Perry