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...@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. :-)
