Re: [PATCH] Improve documentation of Core module in perl bindings

["Hyrum K. Wright" <hy...@mail.utexas.edu>]

Stefan Sperling wrote:
> I spotted a couple of grammatical errors while reading the
> SVN::Core man page. After fixing them I went over the whole
> thing and tried to clear it up a bit. I hope this patch makes
> the docs both more readable and accessible.
> 
> [[[
> * subversion/bindings/swig/perl/native/Core.pm:
> 
> Fix grammatical errors in the documentation.
> Also improve wording here and there to make the documentation
> more clear and accessible.
> Also, there is no 'destroy' function in the code, the author
> probably meant the 'DESTROY' function.
> 
> ]]]

Committed, with a couple of tweaks of my own, in r27316.  Thanks for the
patch.

-Hyrum

> Index: subversion/bindings/swig/perl/native/Core.pm
> ===================================================================
> --- subversion/bindings/swig/perl/native/Core.pm	(revision 26203)
> +++ subversion/bindings/swig/perl/native/Core.pm	(working copy)
> @@ -118,10 +118,11 @@
>  translated into perl io handles, so you could access them with regular
>  print, read, etc.
>  
> -Note that some functions take a stream to read or write, while it
> -does not close it but still hold the reference to the handle. In this case
> -the handle won't be destroyed properly. You should always use correct
> -default pool before calling such functions.
> +Note that some functions take a stream to read from or write to, but do not
> +close the stream while still holding the reference to the io handle.
> +In this case the handle won't be destroyed properly.
> +You should always set up the correct default pool before calling
> +such functions.
>  
>  =cut
>  
> @@ -302,13 +303,12 @@
>  The perl bindings significantly simplify the usage of pools, while 
>  still being manually adjustable.
>  
> -Functions requiring pool as the last argument (which are, almost all
> -of the subversion functions), the pool is optionally. The default pool
> +For functions requiring a pool as the last argument (which are, almost all
> +of the subversion functions), the pool argument is optional. The default pool
>  is used if it is omitted. When C<SVN::Core> is loaded, it creates a
> -pool as the default one, which is also available from
> -C<SVN::Core-E<gt>gpool>.
> +new default pool, which is also available from C<SVN::Core-E<gt>gpool>.
>  
> -For callback functions providing pool to your subroutine, you could
> +For callback functions providing a pool to your subroutine, you could
>  also use $pool-E<gt>default to make it the default pool in the scope.
>  
>  =head3 Methods
> @@ -333,10 +333,10 @@
>  
>  Clear the pool.
>  
> -=item destroy
> +=item DESTROY
>  
> -Destroy the pool. If the pool is the default pool, restore the
> -previous default pool as default. This is normally called
> +Destroy the pool. If the pool was the default pool, restore the
> +previous default pool. This is normally called
>  automatically when the SVN::Pool object is no longer used and
>  destroyed by the perl garbage collector.
>  
> @@ -482,7 +482,7 @@
>  otherwise.  If you leave the parenthesis off around $ci (scalar context) it
>  will be the commit_info object, which in the case of an error will be undef.
>  
> -If you plan on using this exception handling, understanding the exception
> +If you plan on using explicit exception handling, understanding the exception
>  handling system the C API uses is helpful.  You can find information on it in
>  the HACKING file and the API documentation.  Looking at the implementation of
>  SVN::Error::croak_on_error and SVN::Error::expanded_message may be helpful as
> @@ -590,7 +590,7 @@
>  		
>  =item SVN::Error::is_error($value)
>  
> -Returns true if the value is an svn_error type return.  Returns false if the
> +Returns true if value is of type svn_error.  Returns false if the
>  value is anything else or undefined.  This is useful for seeing if a call has
>  returned an error.
>  
> @@ -605,12 +605,12 @@
>  Default error handler.  It takes an svn_error_t and extracts the error messages
>  from it and croaks with those messages.
>  
> -It can be used two ways.  The first is detailed above as setting it as the
> +It can be used in two ways.  The first is detailed above as setting it as the
>  automatic exception handler via setting $SVN::Error::handler. 
>  
>  The 2nd is if you have $SVN::Error::handler set to undef as a wrapper for calls
> -you want to croak on when there is an error but don't want to have to write an
> -explicit error handler for example:
> +you want to croak on when there is an error, but you don't want to write an
> +explicit error handler. For example:
>  
>  my $result_rev=SVN::Error::croak_on_error($ctx-E<gt>checkout($url,$path,'HEAD',1));
>  
> @@ -634,9 +634,9 @@
>  
>  =item SVN::Error::confess_on_error
>  
> -The same as croak_on_error except it will give a more detailed stack backtrace.
> -Including showing internal calls within the implementations of the perl
> -bindings.  This is useful if you're working on developing the bindings.
> +The same as croak_on_error except it will give a more detailed stack backtrace,
> +including internal calls within the implementation of the perl bindings.
> +This is useful when you are doing development work on the bindings themselves.
>  
>  =cut
>  
> 
>