Hi all,
I've noticed that there are quite a few new APIs missing from the Perl
bindings. So I started looking at adding them, and then realised that the
documentation needed a bit of an overhaul.
Rather than try and do both things at once, I've tried to get the
documentation in to a slightly more malleable shape first.
So, this first patch just rejigs the internal documentation of Repos.pm, and
changes the implementation slightly so that as methods are documented (or
added) it's easier to note that that's happened (IMHO).
[[[
Add more detail to the documentation for the SVN::Repos Perl bindings
Rearrange how methods are wrapped in this file, to make it easier to add new
methods in the future while keeping the documentation in sync.
* subversion/bindings/swig/perl/native/Repos.pm:
(@methods): Build up the list of exported methods throughout the file,
which keeps a method's export point nearer its point of documentation.
(POD Documentation): Add documentation for get_logs(). Explicitly list
the other methods that are exported. Bring the example up to date, and
update the copyright date.
]]]
Comments?
N
Index: Repos.pm
===================================================================
--- Repos.pm (revision 21693)
+++ Repos.pm (working copy)
@@ -10,50 +10,173 @@
=head1 SYNOPSIS
- require SVN::Core;
- require SVN::Repos;
- require SVN::Fs;
+ use SVN::Core;
+ use SVN::Repos;
+ use SVN::Fs;
- my $repos = SVN::Repos::open ('/path/to/repos');
- print $repos->fs->youngest_rev;
+ my $repos = SVN::Repos::open('/path/to/repos');
+ print $repos->fs()->youngest_rev;
=head1 DESCRIPTION
-SVN::Repos wraps the functions in svn_repos.h. The actual namespace
-for repos object is _p_svn_repos_t.
+SVN::Repos wraps the object-oriented C<svn_repos_t> functions, providing
+access to a Subversion repository on the local filesystem.
+=cut
+
+# Build up a list of methods as we go through the file. Add each method
+# to @methods, then document it. The full list of methods is then
+# instantiated at the bottom of this file.
+#
+# This should make it easier to keep the documentation and list of methods
+# in sync.
+
+my @methods = (); # List of functions to wrap
+
+push @methods, qw(open create);
+
=head2 CONSTRUCTORS
=over
-=item open ($path)
+=item SVN::Repos::open($path)
-=item create ($path, undef, undef, $config, $fs_config)
+This function opens an existing repository, and returns an
+C<SVN::Repos> object.
+=item create($path, undef, undef, $config, $fs_config)
+
+This function creates a new repository, and returns an C<SVN::Repos>
+object.
+
=back
=head2 METHODS
-Please consult the svn_repos.h section in the Subversion
-API. Functions taking svn_repos_t * as the first inbound argument
-could be used as methods of the object returned by open or create.
+=over
=cut
-package _p_svn_repos_t;
+push @methods, qw(fs);
-my @methods = qw/fs get_logs get_commit_editor get_commit_editor2
- path db_env lock_dir
- db_lockfile hook_dir start_commit_hook
- pre_commit_hook post_commit_hook
- pre_revprop_change_hook post_revprop_change_hook
- dated_revision fs_commit_txn fs_begin_txn_for_commit
- fs_begin_txn_for_update fs_change_rev_prop
- node_editor dump_fs load_fs get_fs_build_parser/;
+=item $repos-E<gt>fs()
-for (@methods) {
+Returns the C<SVN::Fs> object for this repository.
+
+=cut
+
+push @methods, qw(get_logs);
+
+=item $repos-E<gt>get_logs([$path, ...], $start, $end, $discover_changed_paths, $strict_node_history, $receiver)
+
+Iterates over all the revisions that affect the list of paths passed
+as the first parameter, starting at $start, and ending at $end.
+
+$receiver is called for each change. The arguments to $receiver are:
+
+=over
+
+=item $self
+
+The C<SVN::Repos> object.
+
+=item $paths
+
+C<undef> if $discover_changed_paths is false. Otherwise, contains a hash
+of paths that have changed in this revision.
+
+=item $rev
+
+The revision this change occured in.
+
+=item $date
+
+The date and time the revision occured.
+
+=item $msg
+
+The log message associated with this revision.
+
+=item $pool
+
+An C<SVN::Pool> object which may be used in the function.
+
+=back
+
+If $strict_node_history is true then copies will not be traversed.
+
+=back
+
+=cut
+
+=head2 ADDITIONAL METHODS
+
+The following methods work, but are not currently documented in this
+file. Please consult the svn_repos.h section in the Subversion API
+for more details.
+
+=over
+
+=item $repos-E<gt>get_commit_editor(...)
+
+=item $repos-E<gt>get_commit_editor2(...)
+
+=item $repos-E<gt>path(...)
+
+=item $repos-E<gt>db_env(...)
+
+=item $repos-E<gt>lock_dir(...)
+
+=item $repos-E<gt>db_lockfile(...)
+
+=item $repos-E<gt>hook_dir(...)
+
+=item $repos-E<gt>start_commit_hook(...)
+
+=item $repos-E<gt>pre_commit_hook(...)
+
+=item $repos-E<gt>post_commit_hook(...)
+
+=item $repos-E<gt>pre_revprop_change(...)
+
+=item $repos-E<gt>post_revprop_change(...)
+
+=item $repos-E<gt>dated_revision(...)
+
+=item $repos-E<gt>fs_commit_txn(...)
+
+=item $repos-E<gt>fs_being_txn_for_commit(...)
+
+=item $repos-E<gt>fs_being_txn_for_update(...)
+
+=item $repos-E<gt>fs_change_rev_prop(...)
+
+=item $repos-E<gt>node_editor(...)
+
+=item $repos-E<gt>dump_fs(...)
+
+=item $repos-E<gt>load_fs(...)
+
+=item $repos-E<gt>get_fs_build_parser(...)
+
+=back
+
+=cut
+
+push @methods, qw(get_commit_editor get_commit_editor2
+ path db_env lock_dir
+ db_lockfile hook_dir start_commit_hook
+ pre_commit_hook post_commit_hook
+ pre_revprop_change_hook post_revprop_change_hook
+ dated_revision fs_commit_txn fs_begin_txn_for_commit
+ fs_begin_txn_for_update fs_change_rev_prop
+ node_editor dump_fs load_fs get_fs_build_parser);
+
+{
no strict 'refs';
- *{$_} = *{"SVN::Repos::$_"};
+ for (@methods) {
+ *{"_p_svn_repos_t::$_"} = *{$_};
+ }
}
=head1 AUTHORS
@@ -62,7 +185,7 @@
=head1 COPYRIGHT
-Copyright (c) 2003 CollabNet. All rights reserved.
+Copyright (c) 2003-2006 CollabNet. All rights reserved.
This software is licensed as described in the file COPYING, which you
should have received as part of this distribution. The terms are also
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Thu Sep 28 22:26:57 2006