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

Re: How wrong can we get a short doc-string?

From: Julian Foad <julianfoad_at_btopenworld.com>
Date: Fri, 15 Aug 2008 01:00:16 +0100

On Thu, 2008-08-14 at 21:41 +0100, Julian Foad wrote:
> On Thu, 2008-08-14 at 16:31 -0400, Karl Fogel wrote:
> > Julian Foad <julianfoad_at_btopenworld.com> writes:
> > > Nothing heard. Committed revision 32483.
[...]
> > One thing that's not clear is what "the file that is at the root URL of
> > RA_SESSION" means. Often, the root URL of an RA_SESSION is a directory,
> > and there are many files that could be in its root; here there is no
> > clear way here to know which of those files the doc string is talking
> > about. If this function requires that RA_SESSION be rooted at a file,
> > then it should say so, and ideally say what error would be returned if
> > RA_SESSION is rooted at a directory.
> >
> > As far as phrasing goes: I find that sometimes it's conceptually clearer
> > to start from the result effects and work backwards. E.g.:
> >
> > /* Set *FILENAME to the path of (and *PROPS to a hash containing the
> > properties of) the file at revision REV in the root url of
> > RA_SESSION. Store the file's text content in a new temporary file
> > in the same directory as the path WC_TARGET. [todo: need to
> > specify whether WC_TARGET can be a directory or not]
> > Do all allocation in POOL. */
> >
> > Thoughts?

Committed an update in r32485, using most of your suggestions.

I didn't mention what errors would be returned as that's not a necessary
part of its contract, but the rest should be much better now.

Thanks.
- Julian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe_at_subversion.tigris.org
For additional commands, e-mail: dev-help_at_subversion.tigris.org
Received on 2008-08-15 02:00:41 CEST

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

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.