From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 28782 invoked from network); 30 Dec 2003 04:43:20 +0000 Received: from smtp.gentoo.org (128.193.0.39) by eagle.gentoo.oregonstate.edu with DES-CBC3-SHA encrypted SMTP; 30 Dec 2003 04:43:20 +0000 Received: from lists.gentoo.org ([128.193.0.34] helo=eagle.gentoo.org) by smtp.gentoo.org with esmtp (Exim 4.24) id 1AbBix-0002h9-MI for arch-gentoo-portage-dev@lists.gentoo.org; Tue, 30 Dec 2003 04:43:19 +0000 Received: (qmail 21156 invoked by uid 50004); 30 Dec 2003 04:43:16 +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 14482 invoked from network); 30 Dec 2003 04:43:15 +0000 To: gentoo-portage-dev@lists.gentoo.org References: <200312271631.45947.blauwers@gentoo.org> <20031229192218.GA3152@gentoo.org> <87d6a7tip2.fsf@jbms.ath.cx> <200312300055.47898.blauwers@gentoo.org> From: Jeremy Maitin-Shepard Date: Mon, 29 Dec 2003 23:45:41 -0500 In-Reply-To: <200312300055.47898.blauwers@gentoo.org> (Bart Lauwers's message of "Tue, 30 Dec 2003 00:55:47 +0100") Message-ID: <87zndasykq.fsf@jbms.ath.cx> User-Agent: Gnus/5.1003 (Gnus v5.10.3) Emacs/21.3.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain Subject: Re: [gentoo-portage-dev] Re: [gentoo-doc] Re: [gentoo-portage-dev] coveted features X-Archives-Salt: 31c532e1-b491-451b-aa50-9397ce6f59af X-Archives-Hash: 0e4d450b7bb07188e790f05a128a27b2 Bart Lauwers writes: > [snip] > 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.) The quality of the documentation produced by doxygen and similar documentation collectors/generators is generally much higher for very object-oriented code; this is why the Java standard library documentation generated by Javadoc is quite usable, and very likely why the KDE documentation is very good. (I will take your word for it, I have not looked at it myself.) If portage-ng is written in a very object-oriented way, then it is possible that Doxygen-generated documentation will be of reasonable quality (provided that sufficient comments are added to the code). Otherwise, some manually written documentation describing certain components or the interaction of certain components would probably be at least a useful supplement. Indeed, it is in describing the interaction between different components that generated documentation, even of highly object-oriented code, is often less useful. -- Jeremy Maitin-Shepard -- gentoo-portage-dev@gentoo.org mailing list