From owner-cvs-all Mon Mar 10 2:53:16 2003 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 694C737B404; Mon, 10 Mar 2003 02:53:13 -0800 (PST) Received: from axl.seasidesoftware.co.za (axl.seasidesoftware.co.za [196.31.7.201]) by mx1.FreeBSD.org (Postfix) with ESMTP id E399B43FA3; Mon, 10 Mar 2003 02:53:10 -0800 (PST) (envelope-from sheldonh@starjuice.net) Received: from sheldonh by axl.seasidesoftware.co.za with local (Exim 4.12) id 18sKtw-0003n8-00; Mon, 10 Mar 2003 12:53:00 +0200 Date: Mon, 10 Mar 2003 12:53:00 +0200 From: Sheldon Hearn To: Tom Rhodes Cc: "M. Warner Losh" , dwmalone@FreeBSD.org, src-committers@FreeBSD.org, cvs-src@FreeBSD.org, cvs-all@FreeBSD.org Subject: Re: cvs commit: src/sys/dev/kbd kbd.c Message-ID: <20030310105300.GD12316@starjuice.net> Mail-Followup-To: Tom Rhodes , "M. Warner Losh" , dwmalone@FreeBSD.org, src-committers@FreeBSD.org, cvs-src@FreeBSD.org, cvs-all@FreeBSD.org References: <200303092249.h29Mnma3080700@repoman.freebsd.org> <20030309.172900.25160079.imp@bsdimp.com> <20030309225156.7c1ecc11.trhodes@FreeBSD.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20030309225156.7c1ecc11.trhodes@FreeBSD.org> User-Agent: Mutt/1.5.3i Sender: owner-cvs-all@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.ORG On (2003/03/09 22:51), Tom Rhodes wrote: > > I seem to recall objecting to this in the past. If you have ddb > > enabled, then this sysctl is useless.... This fact should at least be > > documented. As should this sysctl... > > Many tunables need documented, its something I've been looking > over. Perhaps a manual page with all the tunables, or a doc in > /usr/share, not sure yet. We've argued about this a lot in the past, and I remember the outcome being as follows from the last time, where I tried and failed: a) Tunables are not documented well enough. b) A sensible place for the source of such documentation to exist, is alongside the declarations of the tunables. c) Our tunable declaration mechanism in the source _already_ supports a field for documentation. d) The most thorough (and likely to stay consistent) approach is to 1) modify the kernel and modules build to include the contents of this documentation field in generated objects, 2) at the end of a build, extract this text from generated objects, and 3) compile the text into a documentation source file, like an mdoc file or fragment. There are all sorts of difficult details involved here, certainly enough to derail me torward the end of my high-energy stint. I even deleted my WIP. You, on the other hand, have demonstrated remarkably high energy levels when it comes to your work for FreeBSD, and I'm willing to bet you're tenacious enough to see it through. :-) Good luck! Ciao, Sheldon. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message