[PATCH] log-related public API docstring clarifications

(See the "SVN-DEV HELP NEEDED: What to do about the ra-get-log interface"
thread for background information.)

C. Michael Pilato wrote:
> Fortunately (for us), I think the docstrings in the RA and repos layers
> are sufficiently vague as to not imply *what* would happen if you passed
> an empty array. So, in my opinion, we have the opportunity in 1.5.0 to
> define that behavior (which we effectively have: empty paths == NULL
> paths == paths with one "" member), and (now) in 1.5.1 to fix the
> docstrings for the repos and RA functions so that this is all made clear.

Attached is a quickie patch to our public API which, I think, accurately
describes the state of the world. Note the @note on svn_ra_get_logs2() --
is that cool? Can we do this?

-- 
C. Michael Pilato <cmpilato_at_collab.net>
CollabNet   <>   www.collab.net   <>   Distributed Development On Demand

Index: subversion/include/svn_repos.h
===================================================================
--- subversion/include/svn_repos.h (revision 31564)
+++ subversion/include/svn_repos.h (working copy)
@@ -1288,7 +1288,9 @@
  * revisions in which at least one of @a paths was changed (i.e., if
  * file, text or props changed; if dir, props or entries changed or any node
  * changed below it). Each path is a <tt>const char *</tt> representing
- * an absolute path in the repository.
+ * an absolute path in the repository. If @a paths is NULL or empty,
+ * show all revisions regardless of what paths were changed in those
+ * revisions.
  *
  * If @a limit is non-zero then only invoke @a receiver on the first
  * @a limit logs.
@@ -1349,7 +1351,8 @@
  * Same as svn_repos_get_logs4(), but with @a receiver being @c
  * svn_log_message_receiver_t instead of @c svn_log_entry_receiver_t.
  * Also, @a include_merged_revisions is set to @c FALSE and @a revprops is
- * svn:author, svn:date, and svn:log.
+ * svn:author, svn:date, and svn:log. If @a paths is empty, nothing
+ * is returned.
  *
  * @since New in 1.2.
  * @deprecated Provided for backward compatibility with the 1.4 API.
Index: subversion/include/svn_ra.h
===================================================================
--- subversion/include/svn_ra.h (revision 31564)
+++ subversion/include/svn_ra.h (working copy)
@@ -1317,6 +1317,12 @@
  *
  * Use @a pool for memory allocation.
  *
+ * @note If @a paths is NULL or empty, the result depends on the
+ * server. Pre-1.5 servers will send nothing; 1.5 servers will
+ * effectively perform the log operation on the root of the
+ * repository. This behavior may be changed in the future to ensure
+ * consistency across all pedigrees of server.
+ *
  * @note Pre-1.5 servers do not support custom revprop retrieval; if @a
  * revprops is NULL or contains a revprop other than svn:author, svn:date,
  * or svn:log, an @c SVN_ERR_RA_NOT_IMPLEMENTED error is returned.