[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

[PATCH] Mostly stylistic changes to SVN::Client documentation

From: John Peacock <jpeacock_at_rowman.com>
Date: 2004-04-11 04:51:04 CEST

Redone patch (originally sent to Ben Reser in private mail)

John

--------

Stylistic changes to Perl SVN::Client

* subversion/bindings/swig/perl/Native/Client.pm
   changes to line length and punctuation
   rewrite several sections to be consistent with each other
   rewrite several sections to aid clarity and add examples

-- 
John Peacock
Director of Information Research and Technology
Rowman & Littlefield Publishing Group
4720 Boston Way
Lanham, MD 20706
301-459-3366 x.5010
fax 301-429-5747

Index: subversion/bindings/swig/perl/native/Client.pm
==================================================================
--- subversion/bindings/swig/perl/native/Client.pm (revision 8458)
+++ subversion/bindings/swig/perl/native/Client.pm (local)
@@ -53,9 +53,13 @@
 
 There are a few notable differences from the C API. Most C function
 calls take a svn_client_ctx_t pointer as the next to last parameter.
-The perl method calls take a SVN::Client object as the first parameter.
-This allows method call invocation of the methods to be possible.
+The Perl method calls take a SVN::Client object as the first parameter.
+This allows method call invocation of the methods to be possible. For
+example, the following are equivalent:
 
+ SVN::Client::add($ctx,$path, $recursive, $pool);
+ $ctx->add($path, $recursive, $pool);
+
 Many of the C API calls also take a apr_pool_t pointer as their last
 argument. The Perl bindings generally deal with this for you and
 you do not need to pass a pool parameter. However, you may still
@@ -146,9 +150,9 @@
 
     KEY DEFAULT
     ---------- ----------------------------------------
- auth auth_baton initiated to provide the
- provider that read cached authentication
- options from the subversion config only.
+ auth auth_baton initiated with providers that
+ read cached authentication options from
+ the subversion config only.
 
     cancel undef
                            
@@ -265,9 +269,9 @@
 Outputs the content of the file identified by $target and $revision to the
 FILEHANDLE. FILEHANDLE is a reference to a filehandle.
 
-If $target is not a local path, then if $revision is 'PREV' (or
-some other kind that requires a local path), an error be raised, because the
-desired revision can not be determined.
+If $target is not a local path and if $revision is 'PREV' (or some
+other kind that requires a local path), then an error will be raised,
+because the desired revision can not be determined.
 
 =item $ctx-E<gt>checkout($url, $path, $revision, $recursive, $pool);
 
@@ -289,8 +293,8 @@
 Commit files or directories referenced by target. Will use the log_msg
 callback to obtain the log message for the commit.
 
-If $targets has no paths (zero elements), then does nothing and immediately
-returns without error.
+If $targets contains no paths (zero elements), then does nothing and
+immediately returns without error.
 
 Calls the notify callback as the commit progresses with any of the following
 actions: $SVN::Wc::Notify::Action::commit_modified,
@@ -302,9 +306,9 @@
 Use $nonrecursive to indicate that subdirectories of directory targets
 should be ignored.
 
-Returns a svn_client_commit_info_t object. If the revision member of the commit
-info object is $SVN::Core::INVALID_REVNUM and no error was raised, then the
-commit was a no-op; nothing needed to be committed.
+Returns a svn_client_commit_info_t object. If the revision member of the
+commit information object is $SVN::Core::INVALID_REVNUM and no error was
+raised, then the commit was a no-op; nothing needed to be committed.
 
 =item $ctx-E<gt>copy($src_target, $src_revision, $dst_target, $pool);
 
@@ -314,11 +318,12 @@
 of a versioned item in the repository. If $src_target is a URL,
 $src_revision is used to choose the revision from which to copy the
 $src_target. $dst_path must be a file or directory under version control,
-or a repository URL, existent or not.
+or a repository URL, existing or not.
 
-If $dst_target is a URL immediately attempt to commit the copy action
+If $dst_target is a URL, immediately attempt to commit the copy action
 to the repository. The log_msg callback will be called to query for a commit
-log message. If the commit succeeds, return a svn_client_commit_info_t object.
+log message. If the commit succeeds, return a svn_client_commit_info_t
+object.
 
 If $dst_target is not a URL, then this is just a variant of $ctx-E<gt>add(),
 where the $dst_path items are scheduled for addition as copies. No changes
@@ -332,10 +337,11 @@
 
 Delete items from a repository or working copy.
 
-If the paths in $targets are URLs, immediate attempt to commit a deletion of the
-URLs from the repository. The log_msg callback will be called to query for
-a commit log message. If the commit succeeds, return a svn_client_commit_info_t object.
-Every path must belong to the same repository.
+If the paths in $targets are URLs, immediately attempt to commit a deletion
+of the URLs from the repository. The log_msg callback will be called to
+query for a commit log message. If the commit succeeds, return a
+svn_client_commit_info_t object. Every path must belong to the same
+repository.
 
 Else, schedule the working copy paths in $targets for removal from the
 repository. Each path's parent must be under revision control. This is
@@ -359,20 +365,20 @@
 node type (i.e. they most both be directories or files). The revisions
 must not be undef.
 
-Prints the output of the diff to the filename or filehandle passed as $outfile, and
-any errors to the filename or filehandle passed as $errfile.
+Prints the output of the diff to the filename or filehandle passed as
+$outfile, and any errors to the filename or filehandle passed as $errfile.
 
 Use $ignore_ancestry to control whether or not items being diffed will be
-checked for relatedness first. Unrelated items are typically transmitted to the
-editor as a deletion of one thing and the addition of another, but if this flag
-is true, unrelated items will be diffed as if they were related.
+checked for relatedness first. Unrelated items are typically transmitted to
+the editor as a deletion of one thing and the addition of another, but if this
+flag is true, unrelated items will be diffed as if they were related.
 
 If $no_diff_deleted is true, then no diff output will be generated on deleted
 files.
 
 $diff_options is a reference to an array of additional arguments to pass to
 diff process invoked to compare files. You'll usually just want to use [] to
-pass an empty array.
+pass an empty array to return a unified context diff (like `diff -u`).
 
 Has no return.
 
@@ -430,9 +436,9 @@
 turn, inclusive (but will never invoke receiver on a given log message more
 than once).
 
-$targets is a reference to an array containing all the paths or URLs for which the
-log messages are desired. The log_receiver is only invoked on messages whose
-revisions involved a change to some path in $targets.
+$targets is a reference to an array containing all the paths or URLs for
+which the log messages are desired. The log_receiver is only invoked on
+messages whose revisions involved a change to some path in $targets.
 
 If $discover_changed_paths is set, then the changed_paths argument to the
 log_receiver routine will be passed on each invocation.
@@ -471,9 +477,8 @@
 
 Returns a hash of svn_dirent_t objects for $target at $revision.
 
-If $target is a directory, returns entries for all of
-the directories contents. If $recursive is true, it will
-recurse subdirectories in $target.
+If $target is a directory, returns entries for all of the directories'
+contents. If $recursive is true, it will recurse subdirectories in $target.
 
 If $target is a file only return an entry for the file.
 
@@ -521,7 +526,7 @@
 
 Create a directory, either in a repository or a working copy.
 
-If $targets contains URLs immediately attempts to commit the creation of the
+If $targets contains URLs, immediately attempts to commit the creation of the
 directories in $targets in the repository. Returns a svn_client_commit_info_t
 object.
 
@@ -575,7 +580,7 @@
 =item $ctx-E<gt>propget($propname, $target, $revision, $recursive, $pool);
 
 Returns a reference to a hash containing paths or URLs, prefixed by $target (a
-working copy or URL), of items of which the property $propname is set, and
+working copy or URL), of items for which the property $propname is set, and
 whose values represent the property value for $propname at that path.
 
 =item $ctx-E<gt>proplist($target, $revision, $recursive, $pool);
@@ -628,7 +633,7 @@
 
 If $path is not in a state of conflict to begin with, do nothing.
 
-If $path's conflict state is removed call the notify callback with the
+If $path's conflict state is removed, call the notify callback with the
 $path.
 
 =item $ctx-E<gt>revert($paths, $recursive, $pool);
@@ -678,15 +683,17 @@
 the working copy at all; it's a pure network operation that changes an
 B<unversioned> property attached to a revision. This can be used to tweak
 log messages, dates, authors, and the like. Be careful: it's a lossy
-operation.
+operation, meaning that any existing value is replaced with the new value,
+with no way to retrieve the prior value.
 
 Also note that unless the administrator creates a pre-revprop-change hook
 in the repository, this feature will fail.
 
 =item $ctx-E<gt>status($path, $revision, \&status_func, $recursive, $get_all, $update, $no_ignore, $pool);
 
-Given $path to a working copy directory (or single file), call status_func with a set of
-svn_wc_status_t objects which describe the status of $path and its children.
+Given $path to a working copy directory (or single file), call status_func()
+with a set of svn_wc_status_t objects which describe the status of $path and
+its children.
 
 If $recursive is true, recurse fully, else do only immediate children.
 
@@ -695,13 +702,14 @@
 
 If $update is set, contact the repository and augment the status objects with
 information about out-of-dateness (with respect to $revision). Also, will
-return the value of the actual revision against with the working copy was compared.
-(The return will be undef if $update is not set).
+return the value of the actual revision against with the working copy was
+compared. (The return will be undef if $update is not set).
 
 The function recurses into externals definitions ('svn:externals') after
 handling the main target, if any exist. The function calls the notify callback
-with $SVN::Wc::Notify::Action::status_external action before handling each externals
-definition, and with $SVN::Wc::Notify::Action::status_completed after each.
+with $SVN::Wc::Notify::Action::status_external action before handling each
+externals definition, and with $SVN::Wc::Notify::Action::status_completed
+after each.
 
 The status_func subroutine takes the following parameters:
 $path, $status
@@ -861,13 +869,13 @@
 
 =item $ctx-E<gt>auth(SVN::Client::get_username_provider());
 
-Provides access the auth_baton in the svn_client_ctx_t attached to the
+Provides access to the auth_baton in the svn_client_ctx_t attached to the
 SVN::Client object.
 
 This method will accept an array or array ref of values returned from the
-authentication provider functions see L</"AUTHENTICATION PROVIDERS">. Which it
-will convert to an auth_baton for you. This is the preferred method of setting
-the auth_baton.
+authentication provider functions see L</"AUTHENTICATION PROVIDERS">, which
+it will convert to an auth_baton for you. This is the preferred method of
+setting the auth_baton.
 
 It will also accept a scalar that references a _p_svn_auth_baton_t such as
 those returned from SVN::Core::auth_open and SVN::Core::auth_open_helper.
@@ -915,8 +923,8 @@
 possible actions values and what they mean. The 3rd is an integer specifying
 the kind of node the path is, which can be: $SVN::Node::none, $SVN::Node::file,
 $SVN::Node::dir, $SVN::Node::unknown. The fourth parameter is the mime-type of
-the file or undef if the mime-type is unknown, it will always be undef for
-directories. The 5th parameter is the state of the file, again see L<SVN::Wc>
+the file or undef if the mime-type is unknown (it will always be undef for
+directories). The 5th parameter is the state of the file, again see L<SVN::Wc>
 for a list of the possible states. The 6th and final parameter is the numeric
 revision number of the changed file. The revision number will be -1 except
 when the action is $SVN::Wc::Notify::Action::update_completed.
@@ -970,7 +978,7 @@
 pass. It always returns the current codereference set.
 
 The subroutine pointed to by this value will be called to see if the operation
-should be canceled. If the operation should be canceled the function may
+should be canceled. If the operation should be canceled, the function may
 return one of the following values:
 
 An svn_error_t object made with SVN::Error::create.
@@ -983,8 +991,8 @@
 with the error code of SVN_ERR_CANCELLED and the string set to the string you
 returned.
 
-Any other value will be interpreted as wanting to continue the operation. Generally,
-it's best to return 0 to continue the operation.
+Any other value will be interpreted as wanting to continue the operation.
+Generally, it's best to return 0 to continue the operation.
 
 =cut
 
@@ -999,8 +1007,8 @@
 
 =item $ctx-E<gt>pool(new SVN::Pool);
 
-Method that sets or gets the pool that is passed to method calls requiring a
-pool but that you didn't pass one.
+Method that sets or gets the default pool that is passed to method calls
+requiring a pool, but which were not explicitly passed one.
 
 See L<SVN::Core> for more information about how pools are managed
 in this interface.
@@ -1021,10 +1029,10 @@
 =item $ctx-E<gt>config(SVN::Core::config_get_config(undef));
 
 Method that allows access to the config member of the svn_client_ctx_t.
-Accepts a perl hash to set, which is what functions like
+Accepts a Perl hash to set, which is what functions like
 SVN::Core:config_get_config() will return.
 
-It will return a _p_arp_hash_t scalar. THis is a temporary
+It will return a _p_arp_hash_t scalar. This is a temporary
 situation. The return value is not particular useful. In
 the future, this value will be tied to the actual hash used
 by the C API.
@@ -1055,7 +1063,7 @@
 information.
 
 The functions that return the svn_auth_provider_object_t for prompt style
-providers take a reference to a perl subroutine to use for the callback. The
+providers take a reference to a Perl subroutine to use for the callback. The
 first parameter each of these subroutines receive is a credential object. The
 subroutines return the response by setting members of that object. Members may
 be set like so: $cred-E<gt>username("breser"); These functions and credential
@@ -1087,10 +1095,10 @@
 
 =item SVN::Client::get_simple_prompt_provider
 
-Returns a simple provider that prompts the user via a callback. Takes two or
+Returns a simple provider that prompts the user via a callback. Takes two or
 three parameters, the first is the callback subroutine, the 2nd is the number
 of retries to allow, the 3rd is optionally a pool. The subroutine gets called
-with the following parameters. A svn_auth_cred_simple_t object, a realm string,
+with the following parameters: a svn_auth_cred_simple_t object, a realm string,
 a default username, may_save, and a pool. The svn_auth_cred_simple has the
 following members: username, password, and may_save.
 
@@ -1101,10 +1109,10 @@
 
 =item SVN::Client::get_username_prompt_provider
 
-Returns a username provider that prompts the user via a callback. Takes two or
+Returns a username provider that prompts the user via a callback. Takes two or
 three parameters, the first is the callback subroutine, the 2nd is the number
 of retries to allow, the 3rd is optionally a pool. The subroutine gets called
-with the following parameters. A svn_auth_cred_username_t object, a realm
+with the following parameters: a svn_auth_cred_username_t object, a realm
 string, a default username, may_save, and a pool. The svn_auth_cred_username
 has the following members: username and may_save.
 
@@ -1135,7 +1143,7 @@
 $SVN::Auth::SSL::OTHER
 
 You reply by setting the accepted_failures of the cred object with an integer
-of the values for what you want to accept bitwise anded together.
+of the values for what you want to accept bitwise AND'd together.
 
 =item SVN::Client::get_ssl_cert_file_provider
 
@@ -1145,7 +1153,7 @@
 =item SVN::Client::get_ssl_cert_prompt_provider
 
 Returns a client certificate provider that prompts the user via a callback.
-Takes two or three parameters, the first is the callback subroutine, the 2nd is
+Takes two or three parameters: the first is the callback subroutine, the 2nd is
 the number of retries to allow, the 3rd is optionally a pool parameter. The
 subroutine gets called with the following parameters. A
 svn_auth_cred_ssl_client_cert object, a realm string, may_save, and a pool.
@@ -1174,7 +1182,7 @@
 
 These are some of the object types that are returned from the methods
 and functions. Others are documented in L<SVN::Core> and L<SVN::Wc>.
-If an object is not documented it is more than likely opaque and
+If an object is not documented, it is more than likely opaque and
 not something you can do anything with, except pass to other functions
 that require such objects.
 

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sun Apr 11 04:51:08 2004

This is an archived mail posted to the Subversion Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.