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

Re: svn commit: r998296 - /subversion/trunk/subversion/include/svn_client.h

From: Daniel Shahaf <d.s_at_daniel.shahaf.name>
Date: Wed, 22 Sep 2010 21:44:50 +0200

Hyrum Wright wrote on Wed, Sep 22, 2010 at 12:14:35 +0100:
> On Wed, Sep 22, 2010 at 11:14 AM, Daniel Shahaf <d.s_at_daniel.shahaf.name> wrote:
> > Julian Foad wrote on Wed, Sep 22, 2010 at 09:43:26 +0100:
> >> So perhaps we should aim to say:
> >>
> >>     * Output the content of a specified revision of a file
> >>     * to a stream.
> >>
> >> The extra words here would not be fluff or "modifying behaviour", but
> >> rather a more accurate description of the primary behaviour.  And this
> >> would give the word "the" something to attach to when we later refer to
> >> "The peg revision", "The stream", and so on.
> >>
> >> Daniel, does that address your concerns?
> >>
> >
> > Yes, I think.  Here's a stab:
> >
> > /**
> >  * Write the content of a specified revision of a versioned node
> >  * to a given stream.
> >  *
> >  * @param[in] out           The given stream, where the content will be written.
> >  * @param[in] path_or_url   The path or URL of the node.
> >  * @param[in] peg_revision  The revision to look up @a path_or_url at.
> >  * @param[in] revision      The revision whose content is to be output.
>
> If the extra prose here helps, that's great. We don't have to be
> minimalist, just consistent. I'd hope we can use the same text for
> every API which takes a peg revision or revision. My goal, at least,
> is for people to be able to look at an API and think "ah, I know what
> those are, because I've used them in these other places over hear" and
> have that be valid, because the docs (and underlying behavior) is
> sanely consistent.

That's a sane goal, of course. I'm just trying to ensure we don't spill
the baby with the bathwater: the doc strings should still /document/
their respective functions; they should explain what a function does,
and not just what standard terms and objects it uses. :-)
Received on 2010-09-22 21:45:52 CEST

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