You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@subversion.apache.org by ju...@apache.org on 2010/08/27 13:22:58 UTC
svn commit: r990103 - in /subversion/trunk/subversion/include: svn_diff.h
svn_props.h svn_ra_svn.h svn_sorts.h svn_wc.h
Author: julianfoad
Date: Fri Aug 27 11:22:58 2010
New Revision: 990103
URL: http://svn.apache.org/viewvc?rev=990103&view=rev
Log:
Fix some Doxygen mark-up.
* subversion/include/svn_diff.h
(svn_hunk_t): Use '@verbatim' for diff hunk examples, as Doxygen was
interpreting some mark-up and doing some formatting inside '<pre>'.
(svn_diff_file_options_t): Use double quotes rather than single quotes to
avoid Doxygen converting '@@' to '@'.
(svn_diff_hunk_reset_*, svn_diff_hunk_get_*): Enable Doxygen.
* subversion/include/svn_props.h
(SVN_PROP_BOOLEAN_TRUE): Enable Doxygen.
(SVN_PROP_EXTERNALS, SVN_PROP_WC_PREFIX): Use '<pre>' instead of
'@verbatim' temporarily to work around a Doxygen bug in which it failed
to recognize the #define and all subsequent ones, issuing messages like
'warning: documentation for unknown define XXX found.'.
* subversion/include/svn_ra_svn.h
(svn_ra_svn_write_tuple): Use '@code' for a C code example, to give nicer
display than '@verbatim'.
* subversion/include/svn_sorts.h
(svn_sort_compare_items_as_paths): Use '@code' for a C code example and
remove embedded mark-up that was being displayed literally.
* subversion/include/svn_wc.h
(svn_wc_add4): Use double quotes rather than single quotes to avoid
Doxygen misinterpreting '@rev' as an invalid command.
(svn_wc_notify_t): Enable Doxygen on recently added members.
(svn_wc_conflict_action_t, svn_wc_conflict_choice_t): Enable Doxygen on the members.
Modified:
subversion/trunk/subversion/include/svn_diff.h
subversion/trunk/subversion/include/svn_props.h
subversion/trunk/subversion/include/svn_ra_svn.h
subversion/trunk/subversion/include/svn_sorts.h
subversion/trunk/subversion/include/svn_wc.h
Modified: subversion/trunk/subversion/include/svn_diff.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_diff.h?rev=990103&r1=990102&r2=990103&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_diff.h (original)
+++ subversion/trunk/subversion/include/svn_diff.h Fri Aug 27 11:22:58 2010
@@ -376,7 +376,7 @@ typedef struct svn_diff_file_options_t
/** Whether to treat all end-of-line markers the same when comparing lines.
* The default is @c FALSE. */
svn_boolean_t ignore_eol_style;
- /** Whether the '@@' lines of the unified diff output should include a prefix
+ /** Whether the "@@" lines of the unified diff output should include a prefix
* of the nearest preceding line that starts with a character that might be
* the initial character of a C language identifier. The default is
* @c FALSE.
@@ -796,30 +796,30 @@ typedef enum svn_diff_operation_kind_e
* - modified text The result of patching the original text.
*
* For example, consider a hunk with the following diff text:
- * <pre>
- * @@ -1,5 +1,5 @@
- * #include <stdio.h>
- * int main(int argc, char *argv[]) {
- * - printf("Hello World!\n");
- * + printf("I like Subversion!\n");
- * }
- * </pre>
+ *
+ * @verbatim
+ @@ -1,5 +1,5 @@
+ #include <stdio.h>
+ int main(int argc, char *argv[]) {
+ - printf("Hello World!\n");
+ + printf("I like Subversion!\n");
+ } @endverbatim
*
* The original text of this hunk is:
- * <pre>
- * #include <stdio.h>
- * int main(int argc, char *argv[]) {
- * printf("Hello World!\n");
- * }
- * </pre>
+ *
+ * @verbatim
+ #include <stdio.h>
+ int main(int argc, char *argv[]) {
+ printf("Hello World!\n");
+ } @endverbatim
*
* And the modified text is:
- * <pre>
- * #include <stdio.h>
- * int main(int argc, char *argv[]) {
- * printf("I like Subversion!\n");
- * }
- * </pre>
+ *
+ * @verbatim
+ #include <stdio.h>
+ int main(int argc, char *argv[]) {
+ printf("I like Subversion!\n");
+ } @endverbatim
*
* @see svn_diff_hunk_readline_diff_text()
* @see svn_diff_hunk_readline_original_text()
@@ -886,53 +886,53 @@ svn_diff_hunk_readline_modified_text(con
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
-/* Reset the diff text of @a hunk so it can be read again from the start.
+/** Reset the diff text of @a hunk so it can be read again from the start.
* @since New in 1.7. */
svn_error_t *
svn_diff_hunk_reset_diff_text(const svn_hunk_t *hunk);
-/* Reset the original text of @a hunk so it can be read again from the start.
+/** Reset the original text of @a hunk so it can be read again from the start.
* @since New in 1.7. */
svn_error_t *
svn_diff_hunk_reset_original_text(const svn_hunk_t *hunk);
-/* Reset the modified text of @a hunk so it can be read again from the start.
+/** Reset the modified text of @a hunk so it can be read again from the start.
* @since New in 1.7. */
svn_error_t *
svn_diff_hunk_reset_modified_text(const svn_hunk_t *hunk);
-/* Return the line offset of the original hunk text,
+/** Return the line offset of the original hunk text,
* as parsed from the hunk header.
* @since New in 1.7. */
svn_linenum_t
svn_diff_hunk_get_original_start(const svn_hunk_t *hunk);
-/* Return the number of lines in the original @a hunk text,
+/** Return the number of lines in the original @a hunk text,
* as parsed from the hunk header.
* @since New in 1.7. */
svn_linenum_t
svn_diff_hunk_get_original_length(const svn_hunk_t *hunk);
-/* Return the line offset of the modified @a hunk text,
+/** Return the line offset of the modified @a hunk text,
* as parsed from the hunk header.
* @since New in 1.7. */
svn_linenum_t
svn_diff_hunk_get_modified_start(const svn_hunk_t *hunk);
-/* Return the number of lines in the modified @a hunk text,
+/** Return the number of lines in the modified @a hunk text,
* as parsed from the hunk header.
* @since New in 1.7. */
svn_linenum_t
svn_diff_hunk_get_modified_length(const svn_hunk_t *hunk);
-/* Return the number of lines of leading context of @a hunk,
+/** Return the number of lines of leading context of @a hunk,
* i.e. the number of lines starting with ' ' before the first line
* that starts with a '+' or '-'.
* @since New in 1.7. */
svn_linenum_t
svn_diff_hunk_get_leading_context(const svn_hunk_t *hunk);
-/* Return the number of lines of trailing context of @a hunk,
+/** Return the number of lines of trailing context of @a hunk,
* i.e. the number of lines starting with ' ' after the last line
* that starts with a '+' or '-'.
* @since New in 1.7. */
Modified: subversion/trunk/subversion/include/svn_props.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_props.h?rev=990103&r1=990102&r2=990103&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_props.h (original)
+++ subversion/trunk/subversion/include/svn_props.h Fri Aug 27 11:22:58 2010
@@ -264,7 +264,7 @@ svn_prop_name_is_valid(const char *prop_
* @{
*/
-/* Properties whose values are interpreted as booleans (such as
+/** Properties whose values are interpreted as booleans (such as
* svn:executable, svn:needs_lock, and svn:special) always fold their
* value to this.
*
@@ -319,13 +319,14 @@ svn_prop_name_is_valid(const char *prop_
*
* The format is a series of lines, such as:
*
- *@verbatim
+ * <pre reason="Should use 'verbatim' instead, but Doxygen v1.6.1 & v1.7.1
+ * then doesn't recognize the #define; presumably a bug.">
localdir1 http://url.for.external.source/etc/
localdir1/foo http://url.for.external.source/foo
localdir1/bar http://blah.blah.blah/repositories/theirproj
localdir1/bar/baz http://blorg.blorg.blorg/basement/code
localdir2 http://another.url/blah/blah/blah
- localdir3 http://and.so.on/and/so/forth @endverbatim
+ localdir3 http://and.so.on/and/so/forth </pre>
*
* The subdir names on the left side are relative to the directory on
* which this property is set.
@@ -398,9 +399,10 @@ svn_prop_name_is_valid(const char *prop_
* For example, WebDAV RA implementations might store a versioned-resource
* url as a WC prop like this:
*
- * @verbatim
+ * <pre reason="Should use 'verbatim' instead, but Doxygen v1.6.1 & v1.7.1
+ * then doesn't recognize the #define; presumably a bug.">
name = svn:wc:dav_url
- val = http://www.example.com/repos/452348/e.289 @endverbatim
+ val = http://www.example.com/repos/452348/e.289 </pre>
*
* The client will try to protect WC props by warning users against
* changing them. The client will also send them back to the RA layer
Modified: subversion/trunk/subversion/include/svn_ra_svn.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_ra_svn.h?rev=990103&r1=990102&r2=990103&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_ra_svn.h (original)
+++ subversion/trunk/subversion/include/svn_ra_svn.h Fri Aug 27 11:22:58 2010
@@ -286,11 +286,11 @@ svn_ra_svn_flush(svn_ra_svn_conn_t *conn
* Use the '!' format specifier to write partial tuples when you have
* to transmit an array or other unusual data. For example, to write
* a tuple containing a revision, an array of words, and a boolean:
- * @verbatim
+ * @code
SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "r(!", rev));
for (i = 0; i < n; i++)
SVN_ERR(svn_ra_svn_write_word(conn, pool, words[i]));
- SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "!)b", flag)); @endverbatim
+ SVN_ERR(svn_ra_svn_write_tuple(conn, pool, "!)b", flag)); @endcode
*/
svn_error_t *
svn_ra_svn_write_tuple(svn_ra_svn_conn_t *conn,
Modified: subversion/trunk/subversion/include/svn_sorts.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_sorts.h?rev=990103&r1=990102&r2=990103&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_sorts.h (original)
+++ subversion/trunk/subversion/include/svn_sorts.h Fri Aug 27 11:22:58 2010
@@ -76,10 +76,10 @@ typedef struct svn_sort__item_t {
* @c apr_array_header_t. For example, to convert hash @a hsh to a sorted
* array, do this:
*
- * @verbatim
- apr_array_header_t *hdr;
- hdr = svn_sort__hash (hsh, @c svn_sort_compare_items_as_paths, pool);
- @endverbatim
+ * @code
+ apr_array_header_t *array;
+ array = svn_sort__hash(hsh, svn_sort_compare_items_as_paths, pool);
+ @endcode
*/
int
svn_sort_compare_items_as_paths(const svn_sort__item_t *a,
Modified: subversion/trunk/subversion/include/svn_wc.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_wc.h?rev=990103&r1=990102&r2=990103&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_wc.h (original)
+++ subversion/trunk/subversion/include/svn_wc.h Fri Aug 27 11:22:58 2010
@@ -1254,7 +1254,7 @@ typedef struct svn_wc_notify_t {
* @since New in 1.7 */
svn_revnum_t old_revision;
- /* These fields are used by svn patch to identify the
+ /** These fields are used by svn patch to identify the
* hunk the notification is for. They are line-based
* offsets and lengths parsed from the unidiff hunk header.
* @since New in 1.7. */
@@ -1263,11 +1263,11 @@ typedef struct svn_wc_notify_t {
svn_linenum_t hunk_modified_start;
svn_linenum_t hunk_modified_length;
- /* The line at which a hunk was matched (and applied).
+ /** The line at which a hunk was matched (and applied).
* @since New in 1.7. */
svn_linenum_t hunk_matched_line;
- /* The fuzz factor the hunk was applied with.
+ /** The fuzz factor the hunk was applied with.
* @since New in 1.7 */
int hunk_fuzz;
@@ -1424,11 +1424,11 @@ typedef svn_error_t *(*svn_wc_get_file_t
*/
typedef enum svn_wc_conflict_action_t
{
- svn_wc_conflict_action_edit, /* attempting to change text or props */
- svn_wc_conflict_action_add, /* attempting to add object */
- svn_wc_conflict_action_delete, /* attempting to delete object */
- svn_wc_conflict_action_replace /* attempting to replace object,
- @since New in 1.7 */
+ svn_wc_conflict_action_edit, /**< attempting to change text or props */
+ svn_wc_conflict_action_add, /**< attempting to add object */
+ svn_wc_conflict_action_delete, /**< attempting to delete object */
+ svn_wc_conflict_action_replace /**< attempting to replace object,
+ @since New in 1.7 */
} svn_wc_conflict_action_t;
@@ -2070,20 +2070,20 @@ svn_wc__conflict_description2_dup(
*/
typedef enum svn_wc_conflict_choice_t
{
- /* Don't resolve the conflict now. Let libsvn_wc mark the path
+ /** Don't resolve the conflict now. Let libsvn_wc mark the path
'conflicted', so user can run 'svn resolved' later. */
svn_wc_conflict_choose_postpone,
- /* If there were files to choose from, select one as a way of
+ /** If there were files to choose from, select one as a way of
resolving the conflict here and now. libsvn_wc will then do the
work of "installing" the chosen file.
*/
- svn_wc_conflict_choose_base, /* original version */
- svn_wc_conflict_choose_theirs_full, /* incoming version */
- svn_wc_conflict_choose_mine_full, /* own version */
- svn_wc_conflict_choose_theirs_conflict, /* incoming (for conflicted hunks) */
- svn_wc_conflict_choose_mine_conflict, /* own (for conflicted hunks) */
- svn_wc_conflict_choose_merged /* merged version */
+ svn_wc_conflict_choose_base, /**< original version */
+ svn_wc_conflict_choose_theirs_full, /**< incoming version */
+ svn_wc_conflict_choose_mine_full, /**< own version */
+ svn_wc_conflict_choose_theirs_conflict, /**< incoming (for conflicted hunks) */
+ svn_wc_conflict_choose_mine_conflict, /**< own (for conflicted hunks) */
+ svn_wc_conflict_choose_merged /**< merged version */
} svn_wc_conflict_choice_t;
@@ -4409,7 +4409,7 @@ svn_wc_delete(const char *path,
* and anything below it will be scheduled for addition inside the parent
* working copy as a copy of the original location. The separate working
* copy will be integrated by this step. In this case, which is only used
- * by code like that of 'svn cp URL@rev path' @a copyfrom_url and
+ * by code like that of "svn cp URL@rev path" @a copyfrom_url and
* @a copyfrom_rev MUST BE the the url and revision of @a local_abspath
* in the separate working copy.
*