Date: Thu, 22 Nov 2001 12:04:52 -0700 From: Chad David <davidc@acns.ab.ca> To: Bruce Evans <bde@zeta.org.au> Cc: "Andrew R. Reiter" <arr@FreeBSD.ORG>, cvs-committers@FreeBSD.ORG, cvs-all@FreeBSD.ORG Subject: Re: cvs commit: src/share/man/man9 VOP_ACCESS.9 Message-ID: <20011122120452.A82953@colnta.acns.ab.ca> In-Reply-To: <20011122174141.C15112-100000@delplex.bde.org>; from bde@zeta.org.au on Thu, Nov 22, 2001 at 06:07:47PM %2B1100 References: <200111201748.fAKHmtc69717@freefall.freebsd.org> <20011122174141.C15112-100000@delplex.bde.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, Nov 22, 2001 at 06:07:47PM +1100, Bruce Evans wrote: > On Tue, 20 Nov 2001, Andrew R. Reiter wrote: > > > arr 2001/11/20 09:48:55 PST > > > > Modified files: > > share/man/man9 VOP_ACCESS.9 > > Log: > > - Fix man page that was broke during KSE merger. This is the first in a > > few commits relating to VOP_* calls and moving in struct thread. > > This is another example of why most section man9 manpages are less than > useful. Many of them do less than echo the code. No one reads them > except to fix bugs in them. I read them, but I suspect that most "seasoned" kernel developers do not. One of the reasons for this could be that the vast majority of the kernel is not documented, and you have a very small chance of getting a hit if you check for a manual page, and in most cases ctags will be much more rewarding. There are people (like me) who are willing to write and update these pages, but there is a large amount of up front work to be done, and then the task of keeping them up to date remains. One of the major problems I have had both writing and verifying correctness is that FreeBSD committers do not seem to think the comments within source files are important (at least keeping them correct), and commit messages do not indicate when changes to interfaces are made. While I understand that these changes are obvious to those involved (or even someone who bothered to read the code), who has the time to track every source change for interface changes just to document them? If the cvs commit message noted the change then someone could easily update the manual page and submit it for review. The other question that I always have is should I just document the interface, or attempt to document the code. For example, no where is the EAGAIN return "flag" from VOP_CLOSE() documented (and perhaps it shouldn't be??), but as a programmer this kind of information is required (without reading vn_close()??). Any comments would be welcome. If most committers feel that section 9 is "less than useful", then I will for sure stop writing them :). -- Chad David davidc@acns.ab.ca ACNS Inc. Calgary, Alberta Canada To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20011122120452.A82953>