From owner-cvs-src@FreeBSD.ORG Tue Sep 28 03:03:49 2004 Return-Path: Delivered-To: cvs-src@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 19E4316A4CE; Tue, 28 Sep 2004 03:03:49 +0000 (GMT) Received: from VARK.MIT.EDU (VARK.MIT.EDU [18.95.3.179]) by mx1.FreeBSD.org (Postfix) with ESMTP id 9D6E743D58; Tue, 28 Sep 2004 03:03:48 +0000 (GMT) (envelope-from das@FreeBSD.ORG) Received: from VARK.MIT.EDU (localhost [127.0.0.1]) by VARK.MIT.EDU (8.13.1/8.12.10) with ESMTP id i8S33lhI018459; Mon, 27 Sep 2004 23:03:47 -0400 (EDT) (envelope-from das@FreeBSD.ORG) Received: (from das@localhost) by VARK.MIT.EDU (8.13.1/8.12.10/Submit) id i8S33lsk018458; Mon, 27 Sep 2004 23:03:47 -0400 (EDT) (envelope-from das@FreeBSD.ORG) Date: Mon, 27 Sep 2004 23:03:47 -0400 From: David Schultz To: "Mark W. Krentel" Message-ID: <20040928030347.GA17987@VARK.MIT.EDU> References: <200409280050.i8S0owSb037260@blue.mwk.domain> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <200409280050.i8S0owSb037260@blue.mwk.domain> cc: alc@FreeBSD.ORG cc: cvs-src@FreeBSD.ORG Subject: Re: cvs commit: src/share/man/man9 Makefile vm_map_entry_resize_free.9 X-BeenThere: cvs-src@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: CVS commit messages for the src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 28 Sep 2004 03:03:49 -0000 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. ;-)