On Thu, 2010-02-11, Daniel Shahaf wrote:
> (Haven't reviewed the full patch; just two quick comments.)
>
> Julian Foad wrote on Thu, 11 Feb 2010 at 11:14 -0000:
> > Please could someone sanity-check this doc clarification. I've been a
> > bit unsure about the exact relationship between node-revs and
> > node-rev-ids and nodes and node-ids and the rest of the FS, and if I've
> > understood right this should help.
> >
> > (I need to re-write the "... node and node-rev are used interchangeably"
> > sentence. I want to explain why that it's OK in certain places for a doc
> > string to talk about "a node" where the corresponding API parameter uses
> > a node-rev-id.)
> >
> > - Julian
> >
> >
>
> > * subversion/include/svn_fs.h
> > Clarify the definition of 'nodes' and 'node revisions'.
> >
> > Index: subversion/include/svn_fs.h
> > ===================================================================
> > --- subversion/include/svn_fs.h (revision 908481)
> > +++ subversion/include/svn_fs.h (working copy)
> > @@ -562,11 +564,24 @@
> > * the filesystem. Instead, we just remove the reference to the node
> > * from the directory.
> > *
> > + * Each node revision is a part of exactly one node. (If it happens to
> > have
> > + * the same content as some other node revision that is part of a different
> ^^^^^^^^^
> > + * node, then those two node revisions can share a single content
> ^^^^
>
> ... or even part of the same node; e.g.,
>
> svn add foo
> svn commit foo
> svn propset k v foo
> svn commit foo
>
> creates two revisions of 'foo' that may share the content representation.
Yup. If I'm going to mention it at all, I should try to be accurate.
> > + * representation but they must remain separate.)
> > + *
> > + * Each node revision is uniquely identified by a node revision id
> > + * (#svn_fs_id_t). A node revision id also identifies which node it is a
> > + * part of.
> > + *
> > + * Within the context of a single revision or transaction, we are talking
> > + * about a single point in time so the terms `node' and `node revision' are
> > + * often interchangeable.
>
> (so *that's* why my search for 'interchangeably' in your diff failed...)
>
> Interchangeable how? Is the term 'node', when in a transaction, used
> interchangeably to refer either to the node or to the node-rev of that
> node which that transaction creates?
(Disambiguating your last few words: the transaction creates the
node-rev, not the node.)
Yes. When we are talking about a revision or transaction, references to
"the node" often implicitly mean "the node as it was in this rev/txn",
in other words "the node-rev".
See, for example, the name and doc string of the function
svn_fs_node_prop():
[[[
/** Set @a *value_p to the value of the property named @a propname of
* @a path in @a root. If the node has no property by that name, set
* @a *value_p to zero. Allocate the result in @a pool.
*/
svn_error_t *
svn_fs_node_prop(svn_string_t **value_p,
svn_fs_root_t *root,
const char *path,
const char *propname,
apr_pool_t *pool);
]]]
"The node" means "the node at that time".
- Julian
