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

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
>
>
>