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