(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.
> + * 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?
> + *
> * @defgroup svn_fs_nodes Filesystem nodes
> * @{
> */
>
