From owner-cvs-all@FreeBSD.ORG  Fri Oct  3 19:00:42 2003
Return-Path: <owner-cvs-all@FreeBSD.ORG>
Delivered-To: cvs-all@freebsd.org
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP
	id 7509916A4B3; Fri,  3 Oct 2003 19:00:42 -0700 (PDT)
Received: from VARK.homeunix.com (adsl-68-122-6-250.dsl.pltn13.pacbell.net
	[68.122.6.250])	by mx1.FreeBSD.org (Postfix) with ESMTP
	id 4826D43FE5; Fri,  3 Oct 2003 19:00:41 -0700 (PDT)
	(envelope-from das@FreeBSD.ORG)
Received: from VARK.homeunix.com (localhost [127.0.0.1])
	by VARK.homeunix.com (8.12.9/8.12.9) with ESMTP id h9420StU065639;
	Fri, 3 Oct 2003 19:00:28 -0700 (PDT)
	(envelope-from das@FreeBSD.ORG)
Received: (from das@localhost)
	by VARK.homeunix.com (8.12.9/8.12.9/Submit) id h9420StZ065638;
	Fri, 3 Oct 2003 19:00:28 -0700 (PDT)
	(envelope-from das@FreeBSD.ORG)
Date: Fri, 3 Oct 2003 19:00:28 -0700
From: David Schultz <das@FreeBSD.ORG>
To: Bruce M Simpson <bms@FreeBSD.ORG>
Message-ID: <20031004020028.GA65508@VARK.homeunix.com>
Mail-Followup-To: Bruce M Simpson <bms@FreeBSD.ORG>,
	src-committers@FreeBSD.ORG, cvs-src@FreeBSD.ORG, cvs-all@FreeBSD.ORG
References: <200310040130.h941U2Ti032910@repoman.freebsd.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <200310040130.h941U2Ti032910@repoman.freebsd.org>
cc: cvs-src@FreeBSD.ORG
cc: src-committers@FreeBSD.ORG
cc: cvs-all@FreeBSD.ORG
Subject: Re: cvs commit: src/share/man/man9 Makefile pmap.9
	pmap_is_prefaultable.9 vm_fault_prefault.9
X-BeenThere: cvs-all@freebsd.org
X-Mailman-Version: 2.1.1
Precedence: list
List-Id: CVS commit messages for the entire tree <cvs-all.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/cvs-all>,
	<mailto:cvs-all-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/cvs-all>
List-Post: <mailto:cvs-all@freebsd.org>
List-Help: <mailto:cvs-all-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/cvs-all>,
	<mailto:cvs-all-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Sat, 04 Oct 2003 02:00:42 -0000

On Fri, Oct 03, 2003, Bruce M Simpson wrote:
> bms         2003/10/03 18:30:02 PDT
> 
>   FreeBSD src repository
> 
>   Modified files:
>     share/man/man9       Makefile pmap.9 
>   Added files:
>     share/man/man9       pmap_is_prefaultable.9 
>                          vm_fault_prefault.9 
>   Log:
>   Update the pmap(9) documentation to reflect the movement of pmap_prefault()
>   to the machine-independent VM layer, as per alc's recent commit.
>   Add a definition for the new pmap_is_prefaultable() helper function.

I appreciate the work that you're doing to document the VM system,
but I'm wondering if it isn't more appropriate to put this sort of
documentation above the functions themselves.  These interfaces
are private to the VM system anyway, so documenting them
separately is just asking for those documents to get out of date.
I'm wondering if your effort would not be better spent improving
the comments in the source code instead.  dillon has already done
a good deal of that, but there is still some dyson code out there
that could use some work in this area.  Just a thought...