Author: stsp
Date: Thu Feb 12 16:44:45 2015
New Revision: 1659311
URL: http://svn.apache.org/r1659311
Log:
On the pin-externals branch, improve API documentation.
* subversion/include/svn_client.h
(svn_client_copy7): Explain what "pinning" an external means and
explain the necessary preconditions for pinning WC externals.
Suggested by: julianfoad
Modified:
subversion/branches/pin-externals/subversion/include/svn_client.h
Modified: subversion/branches/pin-externals/subversion/include/svn_client.h
URL:
http://svn.apache.org/viewvc/subversion/branches/pin-externals/subversion/include/svn_client.h?rev=1659311&r1=1659310&r2=1659311&view=diff
==============================================================================
--- subversion/branches/pin-externals/subversion/include/svn_client.h (original)
+++ subversion/branches/pin-externals/subversion/include/svn_client.h Thu Feb
12 16:44:45 2015
@@ -4494,13 +4494,30 @@ typedef struct svn_client_copy_source_t
*
* If @a pin_externals is set, pin URLs in copied externals definitions
* to their current revision unless they were already pinned to a
- * particular revision. If non-NULL, @a externals_to_pin restricts pinning
- * to a subset of externals. It is a hash table keyed by either a local
- * absolute path or a URL at which an svn:externals property is set.
- * The hash table contains apr_array_header_t* elements as returned
- * by svn_wc_parse_externals_description3(). These arrays contain elements
- * of type svn_wc_external_item2_t*. Externals corresponding to these
- * items will be pinned, other externals will not be pinned.
+ * particular revision. A pinned external uses a URL which points at a
+ * fixed revision, rather than the HEAD revision. Externals in the copy
+ * destination are pinned to either a working copy base revision or the
+ * HEAD revision of a repository (as of the time the copy operation is
+ * performed), depending on the type of the copy source:
+ <pre>
+ copy source: working copy (WC) REPOS
+ ------------+------------------------+---------------------------+
+ copy WC | external's WC BASE rev | external's repos HEAD rev |
+ dest: |------------------------+---------------------------+
+ REPOS | external's WC BASE rev | external's repos HEAD rev |
+ ------------+------------------------+---------------------------+
+ </pre>
+ * If the copy source is a working copy, then all externals must be checked
+ * out, be at a single-revision, contain no local modifications, and contain
+ * no switched subtrees. Else, #SVN_ERR_WC_PATH_UNEXPECTED_STATUS is returned.
+ *
+ * If non-NULL, @a externals_to_pin restricts pinning to a subset of externals.
+ * It is a hash table keyed by either a local absolute path or a URL at which
+ * an svn:externals property is set. The hash table contains
apr_array_header_t*
+ * elements as returned by svn_wc_parse_externals_description3(). These arrays
+ * contain elements of type svn_wc_external_item2_t*, each of which corresponds
+ * to a single line of an svn:externals definition. Externals corresponding to
+ * these items will be pinned, other externals will not be pinned.
* If @a externals_to_pin is @c NULL then all externals are pinned.
* If @a pin_externals is @c FALSE then @a externals_to_pin is ignored.
*
