From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 9790 invoked from network); 30 Dec 2003 00:19:41 +0000 Received: from smtp.gentoo.org (128.193.0.39) by eagle.gentoo.oregonstate.edu with DES-CBC3-SHA encrypted SMTP; 30 Dec 2003 00:19:41 +0000 Received: from lists.gentoo.org ([128.193.0.34] helo=eagle.gentoo.org) by smtp.gentoo.org with esmtp (Exim 4.24) id 1Ab7bo-00002e-Hz for arch-gentoo-portage-dev@lists.gentoo.org; Tue, 30 Dec 2003 00:19:40 +0000 Received: (qmail 27778 invoked by uid 50004); 29 Dec 2003 23:55:52 +0000 Mailing-List: contact gentoo-portage-dev-help@gentoo.org; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail Reply-To: gentoo-portage-dev@lists.gentoo.org X-BeenThere: gentoo-portage-dev@gentoo.org Received: (qmail 10414 invoked from network); 29 Dec 2003 23:55:51 +0000 From: Bart Lauwers To: gentoo-portage-dev@lists.gentoo.org Date: Tue, 30 Dec 2003 00:55:47 +0100 User-Agent: KMail/1.5.4 Cc: gentoo-doc@lists.gentoo.org References: <200312271631.45947.blauwers@gentoo.org> <20031229192218.GA3152@gentoo.org> <87d6a7tip2.fsf@jbms.ath.cx> In-Reply-To: <87d6a7tip2.fsf@jbms.ath.cx> MIME-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit Content-Disposition: inline Message-Id: <200312300055.47898.blauwers@gentoo.org> X-RAVMilter-Version: 8.4.3(snapshot 20030212) (ferengi.skynet.be) Subject: Re: [gentoo-portage-dev] Re: [gentoo-doc] Re: [gentoo-portage-dev] coveted features X-Archives-Salt: 066bd2ce-6246-402a-856f-1c36a5bce406 X-Archives-Hash: bd785b9689767f2a46217bd13e6cfd04 > > Creating documentation automatically always reduces the readability of > > the documentation. It all depends on who's the intended reader. If it is > > a developer (and *only* a developer) then creating documentation > > automatically might be suggesteable (although not official as there is no > > QA on it - don't dare send me bugreports on automatically created > > documentation :) > > > > If it also involves users, then sorry, I don't think this is a good > > idea. > > Indeed, in my experience, documentation generated by Doxygen is very > rarely of decent quality. Provided that people are willing to write > documentation from time to time, ``hand-written'' documentation is > generally of higher quality. If you just want a function reference, it > works, but compare the documentation in linux/Documentation to the > garbage you might get if you were to generate Doxygen documentation from > it. Only developer documentation obviously. But auto generated docs don't have to be bad, most of the kde programming docs are done on the fly and they are more then decent. They're also complete and consistent. In terms of API documentation kde rules, can't we mimik this? (And sorry I kinda felt this was obvious in the request but I do mean a documentation level which isn't maintained by the doc team nor meant for general consumption but a reference guide for devs. And then still split in 2 levels, with one for portage development/ integration and one for ebuild developers.) And consumer doc writers are allowed but not forced to use the API level docs for reference. :) (Well I'm convinced it would make things better on a lot of fronts to have tighter code/doc integration but maybe there is a better way.) Bart -- gentoo-portage-dev@gentoo.org mailing list