[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: WC-NG - Doc strings and API design

From: C. Michael Pilato <cmpilato_at_collab.net>
Date: Mon, 01 Mar 2010 09:27:04 -0500

Julian Foad wrote:
> 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.

+1. Or, +NUMBER_OF_API_FUNCTIONS. This will be very useful to those of us
trying to crack open a can of WC-NG without spilling stuff all over the floor.

-- 
C. Michael Pilato <cmpilato_at_collab.net>
CollabNet   <>   www.collab.net   <>   Distributed Development On Demand

Received on 2010-03-01 15:27:41 CET

This is an archived mail posted to the Subversion Dev mailing list.