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)
@@ -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,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
+ * 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.
+ *
* @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;
@@ -579,8 +594,8 @@
-/** Return non-zero IFF the nodes associated with @a id1 and @a id2 are
- * related, else return zero.
+/** Return non-zero IFF the node revisions associated with @a id1 and @a id2
+ * are related, else return zero.
*/
svn_boolean_t
svn_fs_check_related(const svn_fs_id_t *id1,
@@ -602,7 +617,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 +943,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-rev, you provide a root, and a directory path relative to
+ * that root.
*
* @defgroup svn_fs_roots Filesystem roots
* @{
@@ -1277,6 +1293,7 @@
* under a transaction root). Note that the root of an unmodified transaction
* is not itself considered to be modified; in that case, return the revision
* upon which the transaction was based.
+ * ### "Created" means ... appeared at this path? svn_fs_node_origin_rev()?
*/
svn_error_t *
svn_fs_node_created_rev(svn_revnum_t *revision,
@@ -1289,7 +1306,7 @@
* any temporary allocations. If @a root is a transaction root, @a
* *revision will be set to #SVN_INVALID_REVNUM for any nodes newly
* added in that transaction (brand new files or directories created
- * using #svn_fs_make_dir or #svn_fs_make_file).
+ * using svn_fs_make_dir() or svn_fs_make_file()).
*
* @since New in 1.5.
*/
@@ -1304,6 +1321,7 @@
* function in conjunction with svn_fs_node_created_rev() to perform a
* reverse lookup of the mapping of (path, revision) -> node-id that
* svn_fs_node_id() performs.
+ * ### Huh? These map (path, rev) to (path, rev), not node-id -> (path, rev).
*/
svn_error_t *
svn_fs_node_created_path(const char **created_path,
