More documentation for errors and error handling

Thanks to the reminder of Sander Roobol, I have taken the suggestions from
you and applied them to the patch.

There is a remaining point of discussion though. Currently there are
tex-info files in doc/programmer/design documenting different concepts in Subversion
design. Error handling and pool programming are definitely at the core of
Subversion design, yet neither has documentation in that directory. Only pool
usage has a section in HACKING.

There is a document about handling errors in Subversion, which is (IMHO
mis-)located in subversion/libsvn_subr. If the section about how to write error
messages belongs in HACKING, then doesn't a section about handling errors
belong in it too?!

The patch below updates the current documentation in subversion/libsvn_subr.
Please provide any comments and additions for the patch as well as any
reactions to integrating into HACKING.

bye,

Erik.
PS: The patch below can also be found at
http://encorps.dnsalias.com/svn-public/patches/errors.log-patch

Log:
[[[
Add / update documentation for errors and error handling.

* HACKING
  Add section about writing error message text.

* subversion/libsvn_subr/README.errors
  Update and extend documentation about handling errors.
]]]

Index: subversion/libsvn_subr/README.errors
===================================================================
--- subversion/libsvn_subr/README.errors (revision 7945)
+++ subversion/libsvn_subr/README.errors (working copy)
@@ -1,4 +1,4 @@
-OK, here's how to use exceptions in Subversion (latest draft).
+OK, here's how to use exceptions in Subversion.
 
 
 1. Exceptions are stored in svn_error_t structures:
@@ -20,7 +20,7 @@
 
         return (svn_create_error ((ap_status_t) err,
                                   NULL,
- "User not permitted to write file."
+ "User not permitted to write file"
                                   NULL,
                                   my_pool));
 
@@ -32,9 +32,13 @@
 3. If you *receive* an error, you have three choices:
 
     a) Handle the error yourself. Use either your own code, or just
- call the primitive svn_handle_error(err). (This routine unwinds
- the stack and prints out messages.)
+ call the primitive svn_handle_error(err). (This routine unwinds
+ the error stack and prints out messages.)
 
+ When your routine receives an error which it intends to ignore or
+ handle itself, be sure to clean it up using svn_error_clear(). Any
+ time such an error are not cleared constitutes a *memory leak*.
+
     b) Throw the error upwards, unmodified:
 
         error = some_routine (foo);
@@ -45,7 +49,7 @@
        which does the same thing:
 
        SVN_ERR (some_routine (foo));
-
+
     c) Throw the error upwards, wrapping it in a new error structure
        by including it as the "child" argument:
 
@@ -54,7 +58,7 @@
           {
            svn_error_t *wrapper = svn_create_error (my_errno,
                                                     NULL,
- "Authorization
failed.",
+ "Authorization failed",
                                                     error,
                                                     error->pool);
            return wrapper;
@@ -68,5 +72,20 @@
         error = some_routine (foo);
         if (error)
           {
- return (svn_quick_wrap_error (error, "Authorization failed.");
+ return (svn_quick_wrap_error (error, "Authorization failed");
           }
+
+ The same can (and should) be done by using the SVN_ERR_W() macro:
+
+ SVN_ERR_W ( some_routine (foo),
+ "Authorization failed");
+
+ In cases (b) and (c) it is important to know that resources allocated
by
+ your routine which are associated with a pool, are automatically
cleaned
+ up when the pool is destroyed. This means that there is no need to
+ cleanup these resources before passing the error. There is therefore no
+ reason not to use the SVN_ERR() and SVN_ERR_W() macros.
+
+ Resources associated with pools are:
+ * Memory
+ * Files
Index: HACKING
===================================================================
--- HACKING (revision 7945)
+++ HACKING (working copy)
@@ -19,6 +19,7 @@
    * Secure coding guidelines
    * Document everything
    * Using page breaks
+ * Error message conventions
    * Other conventions
    * APR pool usage conventions
    * APR status codes
@@ -371,6 +372,47 @@
 
 
 
+Error message conventions
+=========================
+
+For error messages the following conventions apply:
+
+ * Provide specific error messages only when there is information
+ to add to the general error message found in
+ subversion/include/svn_error_codes.h
+
+ * Messages start with a capital letter.
+
+ * Try keeping messages below 70 characters.
+
+ * Don't end the error message with a '.'.
+
+ * Don't include newline characters in error messages.
+
+ * Quoting information is done using single quotes ('some info').
+
+ * Don't include the name of the function where the error occurs
+ in the error message. If subversion is compiled using the
+ '--enable-maintainer-mode' configure-flag, if will provide this
+ information by itself.
+
+ * When including path or filenames in the error string, be sure
+ to quote them. (i.e. "Can't find '/path/to/repos/userfile'")
+
+ * When including path or filenames in the error string, be sure
+ to convert them using 'svn_path_local_style ()' before inclusion.
+
+ * If you want to add an explanation to the error, report it
+ followed by a colon and the explanation like this:
+ "Invalid " SVN_PROP_EXTERNALS " property on '%s': "
+ "target involves '.' or '..'"
+
+ * Suggestions or other additions can be added after a semi-colon,
+ like this:
+ "Can't write to '%s': object of same name already exists; remove "
+ "before retrying"
+
+
 Other conventions
 =================
 

-- 
+++ GMX - die erste Adresse für Mail, Message, More +++
Neu: Preissenkung für MMS und FreeMMS! http://www.gmx.net
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org