Author: julianfoad
Date: Tue Nov 14 15:49:33 2017
New Revision: 1815224
URL: http://svn.apache.org/viewvc?rev=1815224&view=rev
Log:
On the 'shelve' branch: Add and update all doc strings.
Modified:
subversion/branches/shelve/BRANCH-README
subversion/branches/shelve/subversion/include/private/svn_wc_private.h
subversion/branches/shelve/subversion/include/svn_client.h
subversion/branches/shelve/subversion/libsvn_client/shelve.c
subversion/branches/shelve/subversion/svn/shelve-cmd.c
Modified: subversion/branches/shelve/BRANCH-README
URL:
http://svn.apache.org/viewvc/subversion/branches/shelve/BRANCH-README?rev=1815224&r1=1815223&r2=1815224&view=diff
==============================================================================
--- subversion/branches/shelve/BRANCH-README (original)
+++ subversion/branches/shelve/BRANCH-README Tue Nov 14 15:49:33 2017
@@ -15,9 +15,8 @@ although the actual copy history of the
Both of the Checkpointing branches therefore include Shelving functionality.
-Initially this is prototyping, to explore the general shape of the design and
-user interface. As such, it does not take care over details of APIs and error
-handling and so on.
+This branch is now at the point of being ready for user testing, and should
+be up to Subversion coding standards, in preparation for merging to trunk.
References:
[0] dev@ thread "[RFC] Shelving and Checkpointing", J Foad, 2017-07-10.
Modified: subversion/branches/shelve/subversion/include/private/svn_wc_private.h
URL:
http://svn.apache.org/viewvc/subversion/branches/shelve/subversion/include/private/svn_wc_private.h?rev=1815224&r1=1815223&r2=1815224&view=diff
==============================================================================
--- subversion/branches/shelve/subversion/include/private/svn_wc_private.h
(original)
+++ subversion/branches/shelve/subversion/include/private/svn_wc_private.h Tue
Nov 14 15:49:33 2017
@@ -348,7 +348,12 @@ svn_wc__get_wcroot(const char **wcroot_a
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
-/* */
+/** Set @a *dir to the abspath of the directory in which shelved patches
+ * are stored, which is inside the WC's administrative directory, and ensure
+ * the directory exists.
+ *
+ * @a local_abspath is any path in the WC, and is used to find the WC root.
+ */
svn_error_t *
svn_wc__get_shelves_dir(char **dir,
svn_wc_context_t *wc_ctx,
Modified: subversion/branches/shelve/subversion/include/svn_client.h
URL:
http://svn.apache.org/viewvc/subversion/branches/shelve/subversion/include/svn_client.h?rev=1815224&r1=1815223&r2=1815224&view=diff
==============================================================================
--- subversion/branches/shelve/subversion/include/svn_client.h (original)
+++ subversion/branches/shelve/subversion/include/svn_client.h Tue Nov 14
15:49:33 2017
@@ -6721,7 +6721,13 @@ svn_client_cat(svn_stream_t *out,
* @{
*/
-/**
+/** Shelve a change.
+ *
+ * Shelve as @a name the local modifications found by @a paths, @a depth,
+ * @a changelists. Revert the shelved change from the WC unless @a keep_local
+ * is true.
+ *
+ * If @a dry_run is true, don't actually do it.
*
* @since New in 1.11.
*/
@@ -6735,7 +6741,12 @@ svn_client_shelve(const char *name,
svn_client_ctx_t *ctx,
apr_pool_t *pool);
-/**
+/** Unshelve the shelved change @a name.
+ *
+ * @a local_abspath is any path in the WC and is used to find the WC root.
+ * Rename the shelved patch to add a '.bak' extension unless @a keep is true.
+ *
+ * If @a dry_run is true, don't actually do it.
*
* @since New in 1.11.
*/
@@ -6747,7 +6758,11 @@ svn_client_unshelve(const char *name,
svn_client_ctx_t *ctx,
apr_pool_t *pool);
-/**
+/** Delete the shelved patch @a name.
+ *
+ * @a local_abspath is any path in the WC and is used to find the WC root.
+ *
+ * If @a dry_run is true, don't actually do it.
*
* @since New in 1.11.
*/
@@ -6758,21 +6773,23 @@ svn_client_shelves_delete(const char *na
svn_client_ctx_t *ctx,
apr_pool_t *pool);
-/**
+/** Information about a shelved patch.
*
* @since New in 1.11.
*/
typedef struct svn_client_shelved_patch_info_t
{
- const char *message;
- const char *patch_path;
- svn_io_dirent2_t *dirent;
- apr_time_t mtime;
+ const char *message; /* first line of log message */
+ const char *patch_path; /* abspath of the patch file */
+ svn_io_dirent2_t *dirent; /* info about the patch file */
+ apr_time_t mtime; /* a copy of dirent->mtime */
} svn_client_shelved_patch_info_t;
/** Set *shelved_patches to a hash, keyed by patch name, of pointers to
* @c svn_client_shelved_patch_info_t structures.
*
+ * @a local_abspath is any path in the WC and is used to find the WC root.
+ *
* @since New in 1.11.
*/
svn_error_t *
@@ -6790,6 +6807,8 @@ svn_client_shelves_list(apr_hash_t **she
* ### Initial implementation isn't O(1) fast -- it just calls
* svn_client_shelves_list().
*
+ * @a local_abspath is any path in the WC and is used to find the WC root.
+ *
* @since New in 1.11.
*/
svn_error_t *
@@ -6798,8 +6817,9 @@ svn_client_shelves_any(svn_boolean_t *an
svn_client_ctx_t *ctx,
apr_pool_t *scratch_pool);
-/** Write local changes to a patch file at @a name.
+/** Write local changes to a patch file for shelved change @a name.
*
+ * @a message: An optional log message.
* @a wc_root_abspath: The WC root dir.
* @a overwrite_existing: If a file at @a patch_abspath exists, overwrite it.
* @a paths, @a depth, @a changelists: The selection of local paths to diff.
@@ -6815,7 +6835,7 @@ svn_client_shelf_write_patch(const char
svn_client_ctx_t *ctx,
apr_pool_t *scratch_pool);
-/** Apply the patch file at @a name to the WC.
+/** Apply the patch file for shelved change @a name to the WC.
*
* @a wc_root_abspath: The WC root dir.
* @a reverse: Apply the patch in reverse.
@@ -6829,7 +6849,7 @@ svn_client_shelf_apply_patch(const char
svn_client_ctx_t *ctx,
apr_pool_t *scratch_pool);
-/** Delete the patch file at @a name.
+/** Delete the patch file for shelved change @a name.
*
* @a wc_root_abspath: The WC root dir.
*/
Modified: subversion/branches/shelve/subversion/libsvn_client/shelve.c
URL:
http://svn.apache.org/viewvc/subversion/branches/shelve/subversion/libsvn_client/shelve.c?rev=1815224&r1=1815223&r2=1815224&view=diff
==============================================================================
--- subversion/branches/shelve/subversion/libsvn_client/shelve.c (original)
+++ subversion/branches/shelve/subversion/libsvn_client/shelve.c Tue Nov 14
15:49:33 2017
@@ -40,7 +40,7 @@
#include "svn_private_config.h"
-/* */
+/* Throw an error if NAME does not conform to our naming rules. */
static svn_error_t *
validate_name(const char *name,
apr_pool_t *scratch_pool)
@@ -52,7 +52,9 @@ validate_name(const char *name,
return SVN_NO_ERROR;
}
-/* */
+/* Set *PATCH_ABSPATH to the abspath of the patch file for shelved change
+ * NAME, no matter whether it exists.
+ */
static svn_error_t *
get_patch_abspath(char **patch_abspath,
const char *name,
@@ -341,7 +343,9 @@ svn_client_shelves_delete(const char *na
return SVN_NO_ERROR;
}
-/* ### Currently just reads the first line.
+/* Set *LOGMSG to the log message stored in the file PATCH_ABSPATH.
+ *
+ * ### Currently just reads the first line.
*/
static svn_error_t *
read_logmsg_from_patch(const char **logmsg,
Modified: subversion/branches/shelve/subversion/svn/shelve-cmd.c
URL:
http://svn.apache.org/viewvc/subversion/branches/shelve/subversion/svn/shelve-cmd.c?rev=1815224&r1=1815223&r2=1815224&view=diff
==============================================================================
--- subversion/branches/shelve/subversion/svn/shelve-cmd.c (original)
+++ subversion/branches/shelve/subversion/svn/shelve-cmd.c Tue Nov 14 15:49:33
2017
@@ -49,10 +49,11 @@ get_name(const char **name,
return SVN_NO_ERROR;
}
-/* */
+/* A comparison function for svn_sort__hash(), comparing the mtime of two
+ svn_client_shelved_patch_info_t's. */
static int
-compare_dirents_by_mtime(const svn_sort__item_t *a,
- const svn_sort__item_t *b)
+compare_shelved_patch_infos_by_mtime(const svn_sort__item_t *a,
+ const svn_sort__item_t *b)
{
svn_client_shelved_patch_info_t *a_val = a->value;
svn_client_shelved_patch_info_t *b_val = b->value;
@@ -73,7 +74,8 @@ list_sorted_by_date(apr_array_header_t *
SVN_ERR(svn_client_shelves_list(&shelved_patch_infos, local_abspath,
ctx, scratch_pool, scratch_pool));
- *list = svn_sort__hash(shelved_patch_infos, compare_dirents_by_mtime,
+ *list = svn_sort__hash(shelved_patch_infos,
+ compare_shelved_patch_infos_by_mtime,
scratch_pool);
return SVN_NO_ERROR;
}
