From dev-return-2282-daniel=haxx.se@subversion.apache.org Mon Mar 1 14:02:38 2010 Return-Path: Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by giant.haxx.se (8.14.3/8.14.3/Debian-9) with SMTP id o21D2bWd026705 for ; Mon, 1 Mar 2010 14:02:38 +0100 Received: (qmail 56236 invoked by uid 500); 1 Mar 2010 13:02:32 -0000 Mailing-List: contact dev-help@subversion.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Delivered-To: mailing list dev@subversion.apache.org Received: (qmail 56228 invoked by uid 99); 1 Mar 2010 13:02:32 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 01 Mar 2010 13:02:32 +0000 X-ASF-Spam-Status: No, hits=1.2 required=10.0 tests=SPF_NEUTRAL X-Spam-Check-By: apache.org Received-SPF: neutral (athena.apache.org: local policy) Received: from [74.125.78.148] (HELO ey-out-1920.google.com) (74.125.78.148) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 01 Mar 2010 13:02:24 +0000 Received: by ey-out-1920.google.com with SMTP id 5so343688eyb.4 for ; Mon, 01 Mar 2010 05:02:02 -0800 (PST) Received: by 10.213.1.132 with SMTP id 4mr3101400ebf.11.1267448522372; Mon, 01 Mar 2010 05:02:02 -0800 (PST) Received: from ?192.168.1.3? (120.20.169.217.in-addr.arpa [217.169.20.120]) by mx.google.com with ESMTPS id 13sm2259795ewy.13.2010.03.01.05.02.01 (version=SSLv3 cipher=RC4-MD5); Mon, 01 Mar 2010 05:02:01 -0800 (PST) Subject: WC-NG - Doc strings and API design From: Julian Foad To: dev@subversion.apache.org Content-Type: text/plain; charset="UTF-8" Date: Mon, 01 Mar 2010 13:02:00 +0000 Message-ID: <1267448520.23854.130.camel@edith> Mime-Version: 1.0 X-Mailer: Evolution 2.28.1 Content-Transfer-Encoding: 7bit We need doc strings. We always do, but especially at this point we need them in order to assist other people in joining the effort to implement WC-NG. I think one of the most useful things I can do at this point is help write them. Doc strings go hand in hand with API design, as I'm sure we all know (subconsciously at least), so as I try to write them I am necessarily examining and trying to guess and then sometimes suggesting changes to the API design. Sometimes that will be a separate step, sometimes part of the same patch. Most of the APIs I'm looking at are private and sparsely documented, and 'wc_db.h' has a comment ending, '... do not want to doc until it feels like it is "Right"'. It seems the time is now Right to consolidate, document, and change where better options are now apparent. I don't want to step on anyone's toes or make gratuitous changes, so let me know if I seem to be doing so. And I'm not going to do the whole API on my own. I'll do some parts. Please step in and fix up another part of it if you can. - Julian