[viewvc-dev] [PATCH] Documentation for rcsparse

Index: common.py
===================================================================
--- common.py	(revision 5080)
+++ common.py	(working copy)
@@ -16,52 +16,199 @@
 import string
 
 class Sink:
+  """Interface to be implemented by clients.  The RCS parser calls this as
+  it parses the RCS file.
+
+  All these methods have stub implementations that do nothing, so you only
+  have to override the callbacks that you care about.
+  """
   def set_head_revision(self, revision):
+    """Reports the head revision for this RCS file.
+
+    This is the value of the 'head' header in the admin section of the RCS
+    file.  This function can only be called before admin_completed().
+
+    Parameter: REVISION is a string containing a revision number.  This is
+    an actual revision number, not a branch number.
+    """
     pass
 
   def set_principal_branch(self, branch_name):
+    """Reports the principal branch for this RCS file.  This is only called
+    if the principal branch is not trunk.
+
+    This is the value of the 'branch' header in the admin section of the RCS
+    file.  This function can only be called before admin_completed().
+
+    Parameter: BRANCH_NAME is a string containing a branch number.  If this
+    function is called, the parameter is typically "1.1.1", indicating the
+    vendor branch.
+    """
     pass
 
   def set_access(self, accessors):
+    """Reports the access control list for this RCS file.  This function is
+    only called if the ACL is set.  If this function is not called then
+    there is no ACL and all users are allowed access.
+
+    This is the value of the 'access' header in the admin section of the RCS
+    file.  This function can only be called before admin_completed().
+
+    Parameter: ACCESSORS is a list of strings.  Each string is a username.
+    The user is allowed access if and only if their username is in the list,
+    OR the user owns the RCS file on disk, OR the user is root.
+
+    Note that CVS typically doesn't use this field.
+    """
     pass
 
   def define_tag(self, name, revision):
+    """Reports a tag or branch definition.  This function will be called
+    once for each tag or branch.
+
+    This is taken from the 'symbols' header in the admin section of the RCS
+    file.  This function can only be called before admin_completed().
+
+    Parameters: NAME is a string containing the tag or branch name.
+    REVISION is a string containing a revision number.  This may be
+    an actual revision number (for a tag) or a branch number.
+
+    The revision number consists of a number of decimal components separated
+    by dots.  There are three common forms.  If there are an odd number of
+    components, it's a branch.  Otherwise, if the next-to-last component is
+    zero, it's a branch (and the next-to-last component is an artifact of
+    CVS and should not be shown to the user).  Otherwise, it's a tag.
+
+    This function is called in the order that the tags appear in the RCS
+    file header.  For CVS, this appears to be in reverse chronological
+    order of tag/branch creation.
+    """
     pass
 
   def set_locker(self, revision, locker):
+    """Reports a lock on this RCS file.  This function will be called once
+    for each lock.
+
+    This is taken from the 'locks' header in the admin section of the RCS
+    file.  This function can only be called before admin_completed().
+
+    Parameters: REVISION is a string containing a revision number.  This is
+    an actual revision number, not a branch number.
+    LOCKER is a string containing a username.
+    """
     pass
 
   def set_locking(self, mode):
-    """Used to signal locking mode.
+    """Signals strict locking mode.  This function will be called if and
+    only if the RCS file is in strict locking mode.
 
-    Called with mode argument 'strict' if strict locking
-    Not called when no locking used."""
+    This is taken from the 'strict' header in the admin section of the RCS
+    file.  This function can only be called before admin_completed().
 
+    Parameters: MODE is always the string 'strict'.
+    """
     pass
 
   def set_comment(self, comment):
+    """Reports the comment for this RCS file.
+
+    This is the value of the 'comment' header in the admin section of the
+    RCS file.  This function can only be called before admin_completed().
+
+    Parameter: COMMENT is a string containing the comment.  This may be
+    multi-line.
+
+    This field does not seem to be used by CVS.    
+    """
     pass
 
   def set_expansion(self, mode):
+    """Reports the keyword expansion mode for this RCS file.
+
+    This is the value of the 'expand' header in the admin section of the
+    RCS file.  This function can only be called before admin_completed().
+
+    Parameter: MODE is a string containing the keyword expansion mode.
+    Possible values include 'o' and 'b', amongst others.
+    """
     pass
 
   def admin_completed(self):
+    """Reports that the initial RCS header has been parsed.  This function is
+    called exactly once.
+    """
     pass
 
   def define_revision(self, revision, timestamp, author, state,
                       branches, next):
+    """Reports metadata about a single revision.
+
+    This function is called for each revision.  It is called later than
+    admin_completed() and earlier than tree_completed().
+
+    Parameter: REVISION is a revision number, as a string.  This is an
+    actual revision number, not a branch number.
+    TIMESTAMP is the date and time that the revision was created, as an
+    integer number of seconds since the epoch.  (I.e. "UNIX time" format).
+    AUTHOR is the author name, as a string.
+    STATE is the state of the revision, as a string.  Common values are
+    "Exp" and "dead".
+    BRANCHES is a list of strings, with each string being an actual
+    revision number (not a branch number).  For each branch which is based
+    on this revision and has commits, the revision number of the first
+    branch commit is listed here.
+    NEXT is either None or a string representing an actual revision number
+    (not a branch number).
+
+    When on trunk, NEXT points to what humans might consider to be the
+    'previous' revision number.  For example, 1.3's NEXT is 1.2.
+    However, on a branch, NEXT really does point to what humans would
+    consider to be the 'next' revision number.  For example, 1.1.2.1's
+    NEXT would be 1.1.2.2.
+    In other words, NEXT always means "where to find the next deltatext
+    that you need this revision to retrieve".
+    """
     pass
 
   def tree_completed(self):
+    """Reports that the RCS revision tree has been parsed.  This function is
+    called exactly once.  This function will be called later than
+    admin_completed().
+    """
     pass
 
   def set_description(self, description):
+    """Reports the description from the RCS file.  This is set using the
+    "-m" flag to "cvs add".  However, many CVS users don't use that option,
+    so this is often empty.
+
+    This function is called once, after tree_completed().
+
+    Parameter: DESCRIPTION is a string containing the description.  This may
+    be multi-line.
+    """
     pass
 
   def set_revision_info(self, revision, log, text):
+    """Reports the log message and contents of a CVS revision.
+
+    This function is called for each revision.  It is called later than
+    set_description().
+
+    Parameters: REVISION is a string containing the actual revision number.
+    LOG is a string containing the log message.  This may be multi-line.
+    TEXT is the contents of the file in this revision, either as full-text or
+    as a diff.  This is usually multi-line, and often quite large and/or
+    binary.
+    """
     pass
 
   def parse_completed(self):
+    """Reports that parsing an RCS file is complete.
+
+    This function is called once.  After it is called, no more calls will be
+    made via this interface.
+    """
     pass
 
 
@@ -208,7 +355,7 @@
     date = self.ts.get()
     self.ts.match(';')
 
-    # Convert date into timestamp
+    # Convert date into standard UNIX time format (seconds since epoch)
     date_fields = string.split(date, '.')
     # According to rcsfile(5): the year "contains just the last two
     # digits of the year for years from 1900 through 1999, and all the
@@ -255,6 +402,7 @@
     #    group	15;
     #    permissions	644;
     #    hardlinks	@configure.in@;
+    #    commitid        mLiHw3bulRjnTDGr;
     # this is "newphrase" in RCSFILE(5). we just want to skip over these.
     while 1:
       token = self.ts.get()
@@ -298,6 +446,15 @@
       self.sink.set_revision_info(revision, log, text)
 
   def parse(self, file, sink):
+    """Parse an RCS file.
+
+    Parameters: FILE is the file object to parse.  (I.e. an object of the
+    built-in Python type "file", usually created using Python's built-in
+    "open()" function).
+    SINK is an instance of (some subclass of) Sink.  It's methods will be
+    called as the file is parsed; see the definition of Sink for the
+    details.
+    """
     self.ts = self.stream_class(file)
     self.sink = sink
 
Index: __init__.py
===================================================================
--- __init__.py	(revision 5080)
+++ __init__.py	(working copy)
@@ -10,8 +10,17 @@
 #
 # -----------------------------------------------------------------------
 
-"""This package provides parsing tools for RCS files."""
+"""This package provides parsing tools for RCS files.
 
+To use this package, first create a subclass of Sink.  This should
+declare all the callback methods you care about.  Create an instance
+of your class, and open() the RCS file you want to read.  Then call
+parse() to parse the file.
+"""
+
+# Make the "Sink" class and the various exception classes visible in this
+# scope.  That way, applications never need to import any of the
+# sub-packages.
 from common import *
 
 try:
@@ -23,4 +32,13 @@
     from default import Parser
 
   def parse(file, sink):
+    """Parse an RCS file.
+
+    Parameters: FILE is the file object to parse.  (I.e. an object of the
+    built-in Python type "file", usually created using Python's built-in
+    "open()" function).  It should be opened in binary mode.
+    SINK is an instance of (some subclass of) Sink.  It's methods will be
+    called as the file is parsed; see the definition of Sink for the
+    details.
+    """
     return Parser().parse(file, sink)