Date: Mon, 27 Sep 2004 23:03:47 -0400 From: David Schultz <das@FreeBSD.ORG> To: "Mark W. Krentel" <krentel@dreamscape.com> Cc: cvs-src@FreeBSD.ORG Subject: Re: cvs commit: src/share/man/man9 Makefile vm_map_entry_resize_free.9 Message-ID: <20040928030347.GA17987@VARK.MIT.EDU> In-Reply-To: <200409280050.i8S0owSb037260@blue.mwk.domain> References: <200409280050.i8S0owSb037260@blue.mwk.domain>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, Sep 27, 2004, Mark W. Krentel wrote: > > This is documentation for a simple static function, so doesn't it > > belong in vm_map.c as a comment, where it is less likely to rot? > > The true purpose of the man page is to describe the rules for > maintaining consistency of the free space variables (adj_free and > max_free). I wanted to elaborate on the free space algorithm in a > format that was too long for program comments, so I chose a manual > page. > > But that brings up the question of the right name for the man page. > Theoretically, vm_map(9) would make sense because adj_free is a field > in struct vm_map_entry. But combining the two pages would clearly > have the tail wagging the dog. > > Another possibility is to pick an original name, say vm_map_freespace(9). > But Alan was concerned about choosing a name that looked like a > function or struct but wasn't one. Finally, we compromised on > vm_map_entry_resize_free(9) since any discussion on the free space > algorithm has to mention this function anyway. > > Anyway, I think it's really too long for program comments, but feel > free to suggest a better man page name. We don't generally have manpages for static kernel functions, much less for their implementation details. (In fact, this may be the first.) It's great that you put together a description at this level of detail, but my concern is that description will be wrong when someone forgets to update the detached documentation later on. Personally, I have no objection to long comments. In addition to paragraph-long descriptions of individual functions, it's common to have long descriptions at the top of files describing the overall design. (At a former employer of mine, these are called ``Big Theory Statements.'') Moreover, your description isn't *that* long; if it were part of vm_map.c, you wouldn't bother repeating the structure of vm_map_entry's or their balanced tree organization, for instance. That's my take on it, but I'm not adamant about it, and I'm not going to argue. If I had that kind of time, I'd spend it doing something more productive. ;-)
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20040928030347.GA17987>