Improve doc strings in libsvn_wc/log.[ch].

* subversion/libsvn_wc/log.c
  (loggy_move_copy_internal): Improve doc string.
  (loggy_path): Add a doc string.

* subversion/libsvn_wc/log.h
  Improve many doc strings. Add questions where clarification is needed.

Index: subversion/libsvn_wc/log.c
===================================================================
--- subversion/libsvn_wc/log.c	(revision 32324)
+++ subversion/libsvn_wc/log.c	(working copy)
@@ -245,7 +245,7 @@
                                        or, if that's NULL, those of NAME.
 
       When SPECIAL_ONLY is TRUE, only translate special,
-      not keywords and eol-style.
+      not keywords and eol-style. ### Ignored: no effect.
 
 */
 static svn_error_t *
@@ -1872,15 +1872,17 @@
 
 /*** Log file generation helpers ***/
 
-/* Extend log_accum with log operations to do MOVE_COPY_OP to SRC_PATH and
+/* Extend LOG_ACCUM with log operations to do MOVE_COPY_OP to SRC_PATH and
  * DST_PATH, removing DST_PATH if no SRC_PATH exists when
  * REMOVE_DST_IF_NO_SRC is true.
  *
- * Sets *DST_MODIFIED (if DST_MODIFIED isn't NULL) to indicate that the
+ * Set *DST_MODIFIED (if DST_MODIFIED isn't NULL) to indicate whether the
  * destination path has been modified after running the log:
  * either MOVE_COPY_OP has been executed, or DST_PATH was removed.
  *
  * SRC_PATH and DST_PATH are relative to ADM_ACCESS.
+ *
+ * For SPECIAL_ONLY, see that argument of file_xfer_under_path().
  */
 static svn_error_t *
 loggy_move_copy_internal(svn_stringbuf_t **log_accum,
@@ -1919,7 +1921,7 @@
       if (dst_modified)
         *dst_modified = TRUE;
     }
-  /* File doesn't exists, the caller wants dst_path to be removed. */
+  /* File doesn't exist, and the caller wants dst_path to be removed. */
   else if (kind == svn_node_none && remove_dst_if_no_src)
     {
       SVN_ERR(svn_wc__loggy_remove(log_accum, adm_access, full_dst, pool));
@@ -1934,6 +1936,9 @@
 
 
 
+/* Return the portion of PATH that is relative to the working copy directory
+ * to which ADM_ACCESS belongs, or SVN_WC_ENTRY_THIS_DIR if PATH is that
+ * directory. PATH must not be outside that directory. */
 static const char *
 loggy_path(const char *path,
            svn_wc_adm_access_t *adm_access)
Index: subversion/libsvn_wc/log.h
===================================================================
--- subversion/libsvn_wc/log.h	(revision 32324)
+++ subversion/libsvn_wc/log.h	(working copy)
@@ -32,8 +32,8 @@
 
 
 
-/* Return the path to use for logfile number LOG_NUMBER.  The returned
-   string will be allocated from POOL.
+/* Return the filename (with no path components) to use for logfile number
+   LOG_NUMBER.  The returned string will be allocated from POOL.
 
    For log number 0, this will just be SVN_WC__ADM_LOG to maintain
    compatibility with 1.0.x.  Higher numbers have the digits of the
@@ -51,6 +51,7 @@
 
 /* Extend **LOG_ACCUM with log instructions to append the contents
    of SRC to DST.
+   SRC and DST are relative to ADM_ACCESS.
 
    This command fails to be idempotent or atomic: there's no way to
    tell if you should re-run this!  This function is deprecated; new
@@ -67,6 +68,7 @@
 
 /* Extend **LOG_ACCUM with log instructions to mark PATH as committed
    with revision REVNUM.
+   ADM_ACCESS is the access baton for PATH.
 */
 svn_error_t *
 svn_wc__loggy_committed(svn_stringbuf_t **log_accum,
@@ -79,7 +81,15 @@
    DST_PATH, if it exists. If it doesn't and REMOVE_DST_IF_NO_SRC is TRUE
    the file at DST_PATH will be deleted if any.
 
-   Sets *DST_MODIFIED, if either the copy or the remove have been carried out.
+   The test for existence is made now, not at log running time.
+
+   SRC_PATH and DST_PATH are relative to ADM_ACCESS.
+
+   Perform textual translations, or not, according to COPY_TYPE.
+
+   Set *DST_MODIFIED (if DST_MODIFIED isn't NULL) to indicate whether the
+   destination path will have been modified after running the log: if either
+   the copy or the remove will have been carried out.
 */
 
 typedef enum svn_wc__copy_t
@@ -108,8 +118,9 @@
 
 
 /* Extend **LOG_ACCUM with log instructions to generate a translated
-   file from SRC to DST with translation settings from VERSIONED
-   and flags specified in FLAGS.
+   file from SRC to DST with translation settings from VERSIONED.
+   ### In what way does VERSIONED provide "translation settings"?
+   DST and SRC and VERSIONED are relative to ADM_ACCESS.
 */
 svn_error_t *
 svn_wc__loggy_translated_file(svn_stringbuf_t **log_accum,
@@ -121,6 +132,7 @@
 
 /* Extend **LOG_ACCUM with log instructions to delete the entry
    associated with PATH from the entries file.
+   ADM_ACCESS is the access baton for PATH.
 */
 svn_error_t *
 svn_wc__loggy_delete_entry(svn_stringbuf_t **log_accum,
@@ -131,6 +143,7 @@
 
 /* Extend **LOG_ACCUM with log instructions to delete lock related
    fields from the entry belonging to PATH.
+   ADM_ACCESS is the access baton for PATH.
 */
 svn_error_t *
 svn_wc__loggy_delete_lock(svn_stringbuf_t **log_accum,
@@ -140,6 +153,7 @@
 
 /* Extend **LOG_ACCUM with log instructions to delete changelist
    from the entry belonging to PATH.
+   ADM_ACCESS is the access baton for PATH.
 */
 svn_error_t *
 svn_wc__loggy_delete_changelist(svn_stringbuf_t **log_accum,
@@ -148,10 +162,10 @@
                                 apr_pool_t *pool);
 
 /* Extend **LOG_ACCUM with commands to modify the entry associated with NAME
-   according to the flags specified in MODIFY_FLAGS, based on the values
-   supplied in *ENTRY.
+   in ADM_ACCESS according to the flags specified in MODIFY_FLAGS, based on
+   the values supplied in *ENTRY.
 
-   The flags in MODIFY_FLAGS are to be taken from the svn_wc__entry_modify
+   The flags in MODIFY_FLAGS are to be taken from the svn_wc__entry_modify()
    parameter by the same name.
 */
 svn_error_t *
@@ -163,7 +177,8 @@
                            apr_pool_t *pool);
 
 /* Extend **LOG_ACCUM with log instructions to modify wcprop PROPNAME
-   for PATH, setting it to PROPVAL.
+   for PATH, setting it to PROPVAL (which may be NULL to delete the property).
+   ADM_ACCESS is the access baton for PATH.
 */
 svn_error_t *
 svn_wc__loggy_modify_wcprop(svn_stringbuf_t **log_accum,
@@ -178,7 +193,13 @@
    DST_PATH, if it exists. If it doesn't and REMOVE_DST_IF_NO_SRC is TRUE
    the file at DST_PATH will be deleted if any.
 
-   Sets *DST_MODIFIED, if either the copy or the remove have been carried out.
+   The test for existence is made now, not at log run time.
+
+   SRC_PATH and DST_PATH are relative to ADM_ACCESS.
+
+   Set *DST_MODIFIED (if DST_MODIFIED isn't NULL) to indicate whether the
+   destination path will have been modified after running the log: if either
+   the move or the remove will have been carried out.
 */
 svn_error_t *
 svn_wc__loggy_move(svn_stringbuf_t **log_accum,
@@ -192,6 +213,8 @@
 
 /* Extend **LOG_ACCUM with log instructions to set permissions of PATH
    to 'executable' if it has the 'executable' property set.
+   The property is tested at log run time, within this log instruction.
+   ADM_ACCESS is the access baton for PATH.
 */
 svn_error_t *
 svn_wc__loggy_maybe_set_executable(svn_stringbuf_t **log_accum,
@@ -202,6 +225,8 @@
 /* Extend **LOG_ACCUM with log instructions to set permissions of PATH
    to 'readonly' if it has the 'needs-lock' property set and there is
    no lock for the file in the working copy.
+   The tests are made at log run time, within this log instruction.
+   ADM_ACCESS is the access baton for PATH.
 */
 svn_error_t *
 svn_wc__loggy_maybe_set_readonly(svn_stringbuf_t **log_accum,
@@ -213,7 +238,8 @@
 /* Extend **LOG_ACCUM with log instructions to set the timestamp of PATH
    in the entry field with name TIME_PROP.
 
-   Use SVN_WC__ENTRY_ATTR_* values for TIME_PROP.
+   Use one of the SVN_WC__ENTRY_ATTR_* values for TIME_PROP.
+   ADM_ACCESS is the access baton for PATH.
 */
 svn_error_t *
 svn_wc__loggy_set_entry_timestamp_from_wc(svn_stringbuf_t **log_accum,
@@ -225,6 +251,7 @@
 
 /* Extend **LOG_ACCUM with log instructions to set the file size of PATH
    in the entries' WORKING_SIZE field.
+   ADM_ACCESS is the access baton for PATH.
 */
 svn_error_t *
 svn_wc__loggy_set_entry_working_size_from_wc(svn_stringbuf_t **log_accum,
@@ -235,6 +262,7 @@
 
 /* Extend **LOG_ACCUM with log instructions to set permissions of PATH
    to 'readonly'.
+   ADM_ACCESS is the access baton for PATH.
 */
 svn_error_t *
 svn_wc__loggy_set_readonly(svn_stringbuf_t **log_accum,
@@ -242,9 +270,10 @@
                            const char *path,
                            apr_pool_t *pool);
 
-/* Extend **LOG_ACCUM with log instructions to set the timestamp of PATH.
+/* Extend **LOG_ACCUM with log instructions to set the timestamp of PATH to
+   the time TIMESTR.
+   ADM_ACCESS is the access baton for PATH.
 */
-
 svn_error_t *
 svn_wc__loggy_set_timestamp(svn_stringbuf_t **log_accum,
                             svn_wc_adm_access_t *adm_access,
@@ -253,7 +282,8 @@
                             apr_pool_t *pool);
 
 /* Extend **LOG_ACCUM with log instructions to remove the file
-   BASE_NAME, if it exists.
+   PATH, if it exists.
+   ADM_ACCESS is the access baton for PATH.
 */
 svn_error_t *
 svn_wc__loggy_remove(svn_stringbuf_t **log_accum,
@@ -272,9 +302,7 @@
 
 /* Create a log file with LOG_NUMBER. Write LOG_CONTENT to it and close-
    and-sync afterwards. ADM_ACCESS must point to a locked working copy.
-
-
-   Helper to eliminate code duplication. */
+*/
 svn_error_t *
 svn_wc__write_log(svn_wc_adm_access_t *adm_access,
                   int log_number, svn_stringbuf_t *log_content,
@@ -284,6 +312,7 @@
 /* Process the instructions in the log file for ADM_ACCESS.
    DIFF3_CMD is the external differ used by the 'SVN_WC__LOG_MERGE'
    log entry.  It is always safe to pass null for this.
+   ### Safe? In what way? What happens? Why would we ever not pass null?
 
    If the log fails on its first command, return the error
    SVN_ERR_WC_BAD_ADM_LOG_START.  If it fails on some subsequent