[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

[PATCH] Doc string update for (de)translation

From: Erik Huelsmann <ehuels_at_gmail.com>
Date: 2005-11-25 22:12:51 CET

On 11/24/05, Julian Foad <julianfoad@btopenworld.com> wrote:
> Erik Huelsmann wrote:
> >
> > Ok. See r17495.
>
> That looks lovely.
>
> > We can take the docstrings from here. I'll post about that in a new thread.
>
> OK.

Here's the patch. It extends some doc strings. I have no idea what
more to put in the log message. Do you have anything to add?

Thanks!

bye,

Erik.

Index: subversion/include/svn_subst.h
===================================================================
--- subversion/include/svn_subst.h (revision 17513)
+++ subversion/include/svn_subst.h (working copy)
@@ -259,10 +259,13 @@

 /**
- * Convenience routine: a variant of svn_subst_translate_stream3()
- * which operates on files. In addition, it will create/detranslate a special
- * file if @a special is @c TRUE.
+ * Translates the file at path @a *src into a file at path @a *dst. The
+ * parameters @a *eol_str, @a repair, @a *keywords and @a expand are
+ * defined the same as in svn_subst_translate_stream3().
  *
+ * In addition, it will create a special file from normal form or
+ * translate one to normal form if @a special is @c TRUE.
+ *
  * Copy the contents of file-path @a src to file-path @a dst atomically,
  * either creating @a dst (or overwriting @a dst if it exists), possibly
  * performing line ending and keyword translations.
@@ -355,8 +358,9 @@
                              svn_boolean_t expand,
                              apr_pool_t *pool);

-/** Convenience routine (wrapper around svn_subst_copy_and_translate3)
- * which detranslates the given @a src into @a dst.
+/**
+ * Translates a file @a *src in working copy form to a file @a *dst in
+ * normal form form.
  *
  * The values specified for @a eol_style, @a *eol_str, @a keywords and
  * @a special, should be the ones used to translate the file to its
@@ -368,6 +372,9 @@
  * returned. By setting @a always_repair_eols to @c TRUE, eols will be
  * made consistent even for those styles which don't have it by default.
  *
+ * @note To translate a file FROM normal form, use
+ * svn_subst_copy_and_translate3().
+ *
  * @since New in 1.4
  *
  */
Index: subversion/include/svn_wc.h
===================================================================
--- subversion/include/svn_wc.h (revision 17513)
+++ subversion/include/svn_wc.h (working copy)
@@ -64,10 +64,22 @@
  * @{
  */

- /** Translate from Normal Format; excludes SVN_WC_TRANSLATE_TO_NF */
+ /** Translate from Normal Form.
+ *
+ * The working copy text bases and repository files are stored
+ * in normal form if they have any svn: properties set which
+ * require translation.
+ *
+ * Either this flag or @c SVN_WC_TRANSLATE_FROM_NF should be specified,
+ * but not both.
+ */
 #define SVN_WC_TRANSLATE_FROM_NF 0x00000000

- /** Translate to Normal Format; excludes SVN_WC_TRANSLATE_FROM_NF */
+ /** Translate to Normal Form.
+ *
+ * Either this flag or @c SVN_WC_TRANSLATE_FROM_NF should be specified,
+ * but not both.
+ */
 #define SVN_WC_TRANSLATE_TO_NF 0x00000001

   /** Force repair of eol styles, making sure the output file consistently
@@ -3165,14 +3177,20 @@
 
 /* EOL conversion and keyword expansion. */

-/** Set @a *xlated_path to a path to translated copy of @src
+/** Set @a *xlated_path to a path to a translated copy of @src
  * or to @a src itself if no translation is necessary.
  * That is, if @a versioned_file's properties indicate newline conversion or
  * keyword expansion, point @a *xlated_path to a copy of @a src
  * whose newlines and keywords are converted using the translation
  * as requested by @a flags.
  *
- * Caller can explicitly request a new file to be returned by setting the
+ * When translating to the normal form, inconsistent eol styles will be
+ * repaired when appropriate for the given setting. When translating
+ * from normal form, no EOL repair is performed (consistency is assumed).
+ * These behaviours can be overridden by specifying either
+ * @c SVN_WC_TRANSLATE_NO_EOL_REPAIR or @c SVN_WC_TRANSLATE_FORCE_EOL_REPAIR.
+ *
+ * The caller can explicitly request a new file to be returned by setting the
  * @c SVN_WC_TRANSLATE_FORCE_COPY flag in @a flags.
  *
  * This function is generally used to get a file that can be compared
@@ -3180,14 +3198,13 @@
  * @c SVN_WC_TRANSLATE_TO_NF is specified, against @a versioned_file itself
  * if @c SVN_WC_TRANSLATE_FROM_NF is specified.
  *
- * Temporary files are created in the temp file area belonging to
- * @a versioned_file.
+ * Output files are created in the temp file area belonging to
+ * @a versioned_file. By default they will be deleted at pool cleanup.
  *
- * If @c SVN_WC_TRANSLATE_DEL_TEMP_ON_POOL_CLEANUP is specified,
- * a pool cleanup handler is registered on *xlated_p if it points to a
- * temporary file.
+ * If @c SVN_WC_TRANSLATE_NO_OUTPUT_CLEANUP is specified, the default
+ * pool cleanup handler to remove @a *xlated_path is not registered.
  *
- * If an error is returned, the effect on @a *xlated_p is undefined.
+ * If an error is returned, the effect on @a *xlated_path is undefined.
  *
  * @since New in 1.4
  */
Received on Fri Nov 25 22:14:42 2005

This is an archived mail posted to the Subversion Dev mailing list.