subversion-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From stef...@apache.org
Subject svn commit: r1695878 - /subversion/branches/svn-mergeinfo-normalizer/tools/client-side/svn-mergeinfo-normalizer/mergeinfo-normalizer.h
Date Fri, 14 Aug 2015 12:26:40 GMT
Author: stefan2
Date: Fri Aug 14 12:26:40 2015
New Revision: 1695878

URL: http://svn.apache.org/r1695878
Log:
On the svn-mergeinfo-normalizer:
Document the internal API.  No functional change.

* tools/client-side/svn-mergeinfo-normalizer/mergeinfo-normalizer.h
  (): Add docstrings to everything.

Modified:
    subversion/branches/svn-mergeinfo-normalizer/tools/client-side/svn-mergeinfo-normalizer/mergeinfo-normalizer.h

Modified: subversion/branches/svn-mergeinfo-normalizer/tools/client-side/svn-mergeinfo-normalizer/mergeinfo-normalizer.h
URL: http://svn.apache.org/viewvc/subversion/branches/svn-mergeinfo-normalizer/tools/client-side/svn-mergeinfo-normalizer/mergeinfo-normalizer.h?rev=1695878&r1=1695877&r2=1695878&view=diff
==============================================================================
--- subversion/branches/svn-mergeinfo-normalizer/tools/client-side/svn-mergeinfo-normalizer/mergeinfo-normalizer.h
(original)
+++ subversion/branches/svn-mergeinfo-normalizer/tools/client-side/svn-mergeinfo-normalizer/mergeinfo-normalizer.h
Fri Aug 14 12:26:40 2015
@@ -42,8 +42,6 @@ extern "C" {
 
 /*** Command dispatch. ***/
 
-typedef struct svn_min__branch_lookup_t svn_min__branch_lookup_t;
-
 /* Hold results of option processing that are shared by multiple
    commands. */
 typedef struct svn_min__opt_state_t
@@ -81,16 +79,31 @@ typedef struct svn_min__opt_state_t
   svn_boolean_t non_interactive;
 } svn_min__opt_state_t;
 
+/* Opaque structure allowing to check efficiently whether a given path
+ * exists in the repository @HEAD. */
+typedef struct svn_min__branch_lookup_t svn_min__branch_lookup_t;
 
+/* Type of the baton passed to any of our sub-commands. */
 typedef struct svn_min__cmd_baton_t
 {
+  /* Preprocessed line options. */
   svn_min__opt_state_t *opt_state;
+
+  /* Client context. */
   svn_client_ctx_t *ctx;
 
+  /* Base path of the directory tree currently being processed. */
   const char *local_abspath;
+
+  /* Working copy root path of LOCAL_ABSPATH. */
   const char *wc_root;
+
+  /* Root of the corresponding working copy. */
   const char *repo_root;
 
+  /* If the sub-command, e.g. the local lookup only 'remove-branches',
+   * needs a specific repository lookup data structure, set it here.
+   * If this is NULL, the sub-command will use remove lookup to REPO_ROOT. */
   svn_min__branch_lookup_t *lookup;
 } svn_min__cmd_baton_t;
 
@@ -117,29 +130,56 @@ svn_error_t *
 svn_min__check_cancel(void *baton);
 
 
-/*** Command-line output functions -- printing to the user. ***/
+/*** Internal API linking the various modules. ***/
 
+/* Set the path and url members in BATON to handle the IDX-th target
+ * specified at the command line.  Allocate the paths in RESULT_POOL and
+ * use SCRATCH_POOL for temporaries. */
 svn_error_t *
 svn_min__add_wc_info(svn_min__cmd_baton_t* baton,
                      int idx,
                      apr_pool_t* result_pool,
                      apr_pool_t* scratch_pool);
 
+/* Scan the working copy sub-tree specified in BATON for mergeinfo and
+ * return them in *RESULT, allocated in RESULT_POOL.  The element type is
+ * opaque.  Use SCRATCH_POOL for temporary allocations. */
 svn_error_t *
 svn_min__read_mergeinfo(apr_array_header_t **result,
                         svn_min__cmd_baton_t *baton,
                         apr_pool_t *result_pool,
                         apr_pool_t *scratch_pool);
 
+/* For the MERGEINFO as returned by svn_min__read_mergeinfo() return the
+ * FS path that is parent to the working copy and all branches mentioned
+ * in the mergeinfo.  Allocate the return value in RESULT_POOL and use
+ * SCRATCH_POOL for temporaries. */
 const char *
 svn_min__common_parent(apr_array_header_t *mergeinfo,
                        apr_pool_t *result_pool,
                        apr_pool_t *scratch_pool);
 
+/* Return the mergeinfo at index IDX in MERGEINFO.
+ * IDX must be 0 .. MERGEINFO->NELTS-1. */
 svn_mergeinfo_t
 svn_min__get_mergeinfo(apr_array_header_t *mergeinfo,
                        int idx);
 
+/* Return the full info on the mergeinfo at IDX in MERGEINFO.  Set *FS_PATH
+ * to the FS path of the respective working copy node, *SUBTREE_RELPATH to
+ * its local absolute path and *PARENT_PATH to the local absolute path of
+ * the working copy node that carries the closest parent mergeinfo.
+ * return the working.  Set *SUBTREE_MERGEINFO to the parsed mergeinfo at
+ * *SUBTREE_RELPATH and *PARENT_MERGEINFO to the parsed mergeinfo at
+ * *PARENT_PATH.
+ *
+ * If there is no parent mergeinfo, *PARENT_PATH will be "" and
+ * *PARENT_MERGEINFO will be NULL.  If IDX is not a valid array index,
+ * "" will be returned for all paths and all mergeinfo will be NULL.
+ *
+ * Note that the returned data is shared with MERGEINFO and has the same
+ * lifetime.  It is perfectly legal to modify the svn_mergeinfo_t hashes
+ * and store the result using svn_min__write_mergeinfo. */
 void
 svn_min__get_mergeinfo_pair(const char **fs_path,
                             const char **parent_path,
@@ -149,29 +189,46 @@ svn_min__get_mergeinfo_pair(const char *
                             apr_array_header_t *mergeinfo,
                             int idx);
 
+/* Store the MERGEINFO in the working copy specified by BATON.  Delete
+ * the mergeinfo on those nodes where it is empty but keep the empty data
+ * in MERGEINFO.  Use SCRATCH_POOL for temporary allocations. */
 svn_error_t *
 svn_min__write_mergeinfo(svn_min__cmd_baton_t *baton,
                          apr_array_header_t *mergeinfo,
                          apr_pool_t *scratch_pool);
 
+/* Remove entries with empty mergeinfo from MERGEINFO. */
 svn_error_t *
 svn_min__remove_empty_mergeinfo(apr_array_header_t *mergeinfo);
 
+/* Print statistics for WC_MERGEINFO to console.  Use SCRATCH_POOL for
+ * temporaries. */
 svn_error_t *
 svn_min__print_mergeinfo_stats(apr_array_header_t *wc_mergeinfo,
                                apr_pool_t *scratch_pool);
 
+/* Opaque data structure containing the log / history downloaded from the
+ * repository. */
 typedef struct svn_min__log_t svn_min__log_t;
 
+/* Data structure describing a copy operation as part of svn_min__log_t. */
 typedef struct svn_min__copy_t
 {
+  /* Copy target FS path. */
   const char *path;
+
+  /* Copy target revision. */
   svn_revnum_t revision;
 
+  /* Copy source FS path. */
   const char *copyfrom_path;
+
+  /* Copy source revision. */
   svn_revnum_t copyfrom_revision;
 } svn_min__copy_t;
 
+/* Fetch the full *LOG for the given URL using the context in BATON.
+ * Allocate *LOG in RESULT_POOL and use SCRATCH_POOL for temporaries. */
 svn_error_t *
 svn_min__log(svn_min__log_t **log,
              const char *url,
@@ -179,12 +236,18 @@ svn_min__log(svn_min__log_t **log,
              apr_pool_t *result_pool,
              apr_pool_t *scratch_pool);
 
+/* Scan LOG and determine what revisions in RANGES actually operate on PATH
+ * or its sub-nodes.  Return those revisions, allocated in RESULT_POOL.
+ * Note that parent path changes don't count as operative within PATH. */
 svn_rangelist_t *
 svn_min__operative(svn_min__log_t *log,
                    const char *path,
                    svn_rangelist_t *ranges,
                    apr_pool_t *result_pool);
 
+/* Scan LOG and determine what revisions in RANGES are operative on PATH
+ * but outside SUBTREE (possibly but not exclusively modifying paths within
+ * SUBTREE).  Return those revisions, allocated in RESULT_POOL. */
 svn_rangelist_t *
 svn_min__operative_outside_subtree(svn_min__log_t *log,
                                    const char *path,
@@ -192,6 +255,10 @@ svn_min__operative_outside_subtree(svn_m
                                    svn_rangelist_t *ranges,
                                    apr_pool_t *result_pool);
 
+/* Scan LOG from START_REV down to END_REV and find the latest deletion of
+ * PATH or a parent thereof and return the revision that contains the
+ * deletion.  Return SVN_INVALID_REVNUM if no such deletion could be found.
+ * Use SCRATCH_POOL for temporaries. */
 svn_revnum_t
 svn_min__find_deletion(svn_min__log_t *log,
                        const char *path,
@@ -199,12 +266,18 @@ svn_min__find_deletion(svn_min__log_t *l
                        svn_revnum_t end_rev,
                        apr_pool_t *scratch_pool);
 
+/* Scan LOG for deletions of PATH or any of its parents.  Return an array,
+ * allocated in RESULT_POOL, containing all svn_revnum_t that contain such
+ * deletions in ascending order.  Use SCRATCH_POOL for temporaries. */
 apr_array_header_t *
 svn_min__find_deletions(svn_min__log_t *log,
                         const char *path,
                         apr_pool_t *result_pool,
                         apr_pool_t *scratch_pool);
 
+/* Scan LOG for the latest copy of PATH or any of its parents no later than
+ * START_REV and no earlier than END_REV.  Return SVN_INVALID_REVNUM if no
+ * such revision exists.  Use SCRATCH_POOL for temporaries. */
 svn_revnum_t
 svn_min__find_copy(svn_min__log_t *log,
                    const char *path,
@@ -212,6 +285,11 @@ svn_min__find_copy(svn_min__log_t *log,
                    svn_revnum_t end_rev,
                    apr_pool_t *scratch_pool);
 
+/* Scan LOG for copies of PATH, any of its parents or sub-nodes made from
+ * revisions no later than START_REV and no earlier than END_REV.  Return
+ * those copies as svn_min__copy_t* in an array allocated in RESULT_POOL.
+ * The copy objects themselves are shared with LOG.  Use SCRATCH_POOL
+ * for temporary allocations. */
 apr_array_header_t *
 svn_min__get_copies(svn_min__log_t *log,
                     const char *path,
@@ -220,6 +298,15 @@ svn_min__get_copies(svn_min__log_t *log,
                     apr_pool_t *result_pool,
                     apr_pool_t *scratch_pool);
 
+/* Return the opaque history object for PATH, starting at START_REV and
+ * going back to its initial creation or END_REV - whichever is latest.
+ *
+ * The history is a sequence of segments, each describing that the node
+ * existed at a given path for a given range of revisions.  Between two
+ * segments, there must have been a copy operation.
+ *
+ * Allocate the result in RESULT_POOL and use SCRATCH_POOL for temporaries.
+ */
 apr_array_header_t *
 svn_min__get_history(svn_min__log_t *log,
                      const char *path,
@@ -228,15 +315,22 @@ svn_min__get_history(svn_min__log_t *log
                      apr_pool_t *result_pool,
                      apr_pool_t *scratch_pool);
 
+/* Return the (potentially empty) parts of LHS and RHS where their history
+ * overlaps, i.e. those (partial) history segments where they have the same
+ * path for in the same revisions.  Allocate the result in RESULT_POOL. */
 apr_array_header_t *
 svn_min__intersect_history(apr_array_header_t *lhs,
                            apr_array_header_t *rhs,
                            apr_pool_t *result_pool);
 
+/* Return the revision ranges that are covered by the segments in HISTORY.
+ * Allocate the result in RESULT_POOL. */
 svn_rangelist_t *
 svn_min__history_ranges(apr_array_header_t *history,
                         apr_pool_t *result_pool);
 
+/* Allocate a new path lookup object in RESULT_POOL and make it use SESSION
+ * for any future repository lookups. */
 svn_min__branch_lookup_t *
 svn_min__branch_lookup_create(svn_ra_session_t *session,
                               apr_pool_t *result_pool);



Mime
View raw message