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