svn commit: r1041891 - /subversion/trunk/subversion/include/svn_types.h

[cm...@apache.org]

Author: cmpilato
Date: Fri Dec  3 16:05:20 2010
New Revision: 1041891

URL: http://svn.apache.org/viewvc?rev=1041891&view=rev
Log:
* subversion/include/svn_types.h
  (svn_error_t): Flesh out the documentation for this structure's members.

Modified:
    subversion/trunk/subversion/include/svn_types.h

Modified: subversion/trunk/subversion/include/svn_types.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_types.h?rev=1041891&r1=1041890&r2=1041891&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_types.h (original)
+++ subversion/trunk/subversion/include/svn_types.h Fri Dec  3 16:05:20 2010
@@ -71,22 +71,44 @@ extern "C" {
  */
 typedef struct svn_error_t
 {
-  /** APR error value, possibly SVN_ custom err */
+  /** APR error value; possibly an SVN_ custom error code (see
+   * `svn_error_codes.h' for a full listing).
+   */
   apr_status_t apr_err;
 
-  /** details from producer of error */
+  /** Details from the producer of error.
+   *
+   * Note that if this error was generated by Subversion's API, you'll
+   * probably want to use svn_err_best_message() to get a single
+   * decriptive string for this error chain (see the @a child member)
+   * or svn_handle_error2() to print the error chain in full.  This is
+   * because Subversion's API functions sometimes add many links to
+   * the error chain that lack details (used only to produce virtual
+   * stack traces).  (Use svn_error_purge_tracing() to remove those
+   * trace-only links from the error chain.)
+   */
   const char *message;
 
-  /** ptr to the error we "wrap" */
+  /** Pointer to the error we "wrap" (may be @c NULL).  Via this
+   * member, individual error object can be strung together into an
+   * "error chain".
+   */
   struct svn_error_t *child;
 
-  /** The pool holding this error and any child errors it wraps */
+  /** The pool in which this error object is allocated.  (If
+   * Subversion's APIs are used to manage error chains, then this pool
+   * will contain the whole error chain of which this object is a
+   * member.) */
   apr_pool_t *pool;
 
-  /** Source file where the error originated.  Only used iff @c SVN_DEBUG. */
+  /** Source file where the error originated (iff @c SVN_DEBUG;
+   * undefined otherwise).
+   */
   const char *file;
 
-  /** Source line where the error originated.  Only used iff @c SVN_DEBUG. */
+  /** Source line where the error originated (iff @c SVN_DEBUG;
+   * undefined otherwise).
+   */
   long line;
 
 } svn_error_t;