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

Re: [PATCH] svn_fs.h doc updates on 'nodes' and 'node revisions'

From: Julian Foad <julian.foad_at_wandisco.com>
Date: Thu, 11 Feb 2010 17:48:07 +0000

OK, here's an update:

[[[
* 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 908933)
+++ subversion/include/svn_fs.h (working copy)
@@ -537,7 +537,7 @@
 /** @} */
 
 

-/** Filesystem Nodes.
+/** Filesystem Nodes and Node-Revisions.
  *
  * In a Subversion filesystem, a `node' corresponds roughly to an
  * `inode' in a Unix filesystem:
@@ -550,9 +550,11 @@
  * different name. So a node's identity isn't bound to a particular
  * filename.
  *
- * A `node revision' refers to a node's contents at a specific point in
- * time. Changing a node's contents always creates a new revision of that
- * node. Once created, a node revision's contents never change.
+ * A `node revision' refers to one particular version of a node's contents,
+ * that existed over a specific period of time (one or more repository
+ * revisions). Changing a node's contents always creates a new revision of
+ * that node, which is to say creates a new `node revision'. Once created,
+ * a node revision's contents never change.
  *
  * When we create a node, its initial contents are the initial revision of
  * the node. As users make changes to the node over time, we create new
@@ -562,16 +564,30 @@
  * the filesystem. Instead, we just remove the reference to the node
  * from the directory.
  *
+ * Each node revision is a part of exactly one node, and appears only once
+ * in the history of that node. It is uniquely identified by a node
+ * revision id, #svn_fs_id_t. Its node revision id also identifies which
+ * node it is a part of.
+ *
+ * @note: Often when we talk about `the node' within the context of a single
+ * revision (or transaction), we implicitly mean `the node as it appears in
+ * this revision (or transaction)', or in other words `the node revision'.
+ *
+ * @note: Commonly, a node revision will have the same content as some other
+ * node revisions in the same node and in different nodes. The FS libraries
+ * allow different node revisions to share the same data without storing a
+ * separate copy of the data.
+ *
  * @defgroup svn_fs_nodes Filesystem nodes
  * @{
  */
 
-/** An object representing a node-id. */
+/** An object representing a node-revision id. */
 typedef struct svn_fs_id_t svn_fs_id_t;
 
 
-/** Return -1, 0, or 1 if node revisions @a a and @a b are unrelated,
- * equivalent, or otherwise related (respectively).
+/** Return -1, 0, or 1 if node revisions @a a and @a b are respectively
+ * unrelated, equivalent, or otherwise related (part of the same node).
  */
 int
 svn_fs_compare_ids(const svn_fs_id_t *a,
@@ -579,8 +595,8 @@
 
 
 
-/** Return non-zero IFF the nodes associated with @a id1 and @a id2 are
- * related, else return zero.
+/** Return TRUE if node revisions @a id1 and @a id2 are related (part of the
+ * same node), else return FALSE.
  */
 svn_boolean_t
 svn_fs_check_related(const svn_fs_id_t *id1,
@@ -602,7 +618,7 @@
 
 
 /** Return a Subversion string containing the unparsed form of the
- * node or node revision id @a id. Allocate the string containing the
+ * node revision id @a id. Allocate the string containing the
  * unparsed form in @a pool.
  */
 svn_string_t *
@@ -928,7 +944,8 @@
  *
  * An #svn_fs_root_t object represents the root directory of some
  * revision or transaction in a filesystem. To refer to particular
- * node, you provide a root, and a directory path relative that root.
+ * node or node revision, you provide a root, and a directory path
+ * relative to that root.
  *
  * @defgroup svn_fs_roots Filesystem roots
  * @{
]]]

- Julian
Received on 2010-02-11 18:49:01 CET

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