[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: Greg Stein <gstein_at_gmail.com>
Date: Mon, 1 Mar 2010 18:03:05 -0500

Thanks!

The current stuff has worked when it was just Hyrum and I, but you're
right: as we scale up the number of people, they become more important
to do "now" rather than "later".

Most of the wc_db "operation" functions are unknown since we haven't
tried to implement around them. Even the functions for maintaining the
BASE nodes aren't really used. One particular pattern missing across
the entire API is passing in an svn_skel_t for one or more work items
to be transactionally inserted into WORK_QUEUE at the same time as the
other database operations are performed. The work item(s) describe
filesystem changes that need to occur to bring the on-disk world
inline with the database view of the world.

(compared to today, where the work items kind of do a mix of
filesystem and database changes; they should only be doing filesystem
in the future)

Cheers,
-g

On Mon, Mar 1, 2010 at 08:02, Julian Foad <julian.foad_at_wandisco.com> 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.
>
> - Julian
>
>
>
Received on 2010-03-02 00:03:42 CET

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