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

[PATCH] wc-metadata.sql - more doc strings

From: Julian Foad <julianfoad_at_btopenworld.com>
Date: Fri, 19 Feb 2010 15:09:53 +0000

Bert, Greg, Hyrum, etc. - please see below several more suggested doc
updates/fixes/questions. Please comment, and please feel free to commit
the ones that are good or use them as starting points for better
updates.

(I'm not so much trying to get patches committed, I'm trying to get
folks to understand and agree on the definitions. I'm open to other
suggestions on how to go about it if this doesn't feel the best way.)

- Julian

[[[
*
  (BASE_NODE, WORKING_NODE, ACTUAL_NODE): Tweak doc strings on
    several columns. One particular change is to say "is null when
    ..." to avoid the ambiguity of "may be null when ...".
]]]

[[[
Index: subversion/libsvn_wc/wc-metadata.sql
===================================================================
--- subversion/libsvn_wc/wc-metadata.sql (revision 911819)
+++ subversion/libsvn_wc/wc-metadata.sql (working copy)
@@ -83,11 +83,13 @@ CREATE TABLE BASE_NODE (
   wc_id INTEGER NOT NULL REFERENCES WCROOT (id),
   local_relpath TEXT NOT NULL,
 
   /* the repository this node is part of, and the relative path [to its
- root] within that repository. these may be NULL, implying it should
- be derived from the parent and local_relpath. non-NULL typically
- indicates a switched node.
+ root] within revision "revnum" of that repository. These may be NULL,
+ implying they should be derived from the parent and local_relpath.
+ Non-NULL typically indicates a switched node.
+ ### Better: 'These two columns and "revnum" may all be null, implying
+ ### ...'?
 
      Note: they must both be NULL, or both non-NULL. */
   repos_id INTEGER REFERENCES REPOSITORY (id),
   repos_relpath TEXT,
@@ -100,27 +102,36 @@ CREATE TABLE BASE_NODE (
   /* Is this node "present" or has it been excluded for some reason?
      The "base-deleted" presence value is not allowed. */
   presence TEXT NOT NULL,
 
- /* what kind of node is this? may be "unknown" if the node is not present */
+ /* The node kind: "file", "dir", or "symlink", or "unknown" if the node is
+ not present. */
   kind TEXT NOT NULL,
 
- /* this could be NULL for non-present nodes -- no info. */
+ /* The revision number in which "repos_relpath" applies in "repos_id".
+ May be NULL, implying it should be derived from the parent.
+ (### Can't be null if repos_relpath is not null.)
+ Non-NULL typically indicates a switched node.*/
   revnum INTEGER,
 
- /* if this node is a file, then the checksum and its translated size
- (given the properties on this file) are specified by the following
- two fields. translated_size may be NULL if the size has not (yet)
- been computed. The kind of checksum (e.g. SHA-1, MD5) is stored in the
- value */
+ /* If this node is a file, then the SHA-1 checksum of the pristine text. */
   checksum TEXT,
+
+ /* The size in bytes of the working file when it had no local text
+ modifications. This means the size of the text when translated from
+ repository-normal format to working copy format with EOL style
+ translated and keywords expanded according to the properties in the
+ "properties" column of this row.
+
+ NULL if this node is not a file or if the size has not (yet) been
+ computed. */
   translated_size INTEGER,
 
   /* Information about the last change to this node. changed_rev must be
      not-null if this node has presence=="normal". changed_date and
      changed_author may be null if the corresponding revprops are missing.
 
- All three values may be null for non-present nodes. */
+ All three values are null for a not-present node. */
   changed_rev INTEGER,
   changed_date INTEGER, /* an APR date/time (usec since 1970) */
   changed_author TEXT,
 
@@ -261,20 +272,27 @@ CREATE TABLE WORKING_NODE (
 
   /* the kind of the new node. may be "unknown" if the node is not present. */
   kind TEXT NOT NULL,
 
- /* if this node was added-with-history AND is a file, then the checksum
- and its translated size (given the properties on this file) are
- specified by the following two fields. translated_size may be NULL
- if the size has not (yet) been computed. */
+ /* The SHA-1 checksum of the pristine text, if this node is a file and was
+ added-with-history, else NULL. */
   checksum TEXT,
+
+ /* The size in bytes of the working file when it had no local text
+ modifications. This means the size of the text when translated from
+ repository-normal format to working copy format with EOL style
+ translated and keywords expanded according to the properties in the
+ "properties" column of this row.
+
+ NULL if this node is not a file or is not added-with-history or if
+ the size has not (yet) been computed. */
   translated_size INTEGER,
 
   /* If this node was added-with-history, then the following fields may
      have information about their source node. See BASE_NODE.changed_* for
      more information.
 
- For added or not-present nodes, these may be null. */
+ For an added or not-present node, these are null. */
   changed_rev INTEGER,
   changed_date INTEGER, /* an APR date/time (usec since 1970) */
   changed_author TEXT,
 
]]]

- Julian
Received on 2010-02-19 16:10:34 CET

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