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

Re: [PATCH] Add some RDoc comments to the SWIG/Ruby bindings, part 1

From: Kobayashi Noritada <nori1_at_dolphin.c.u-tokyo.ac.jp>
Date: 2006-06-23 00:48:53 CEST

Good morning and bad results of the football game for Japan, ;-p

Mostly corrected as pointed out. But I have just one question:

> > + # Following methods are also available:
> > + #
> > + # [path]
> > + # Returns a path concerned with the instance.
> > + # [prop_changed]
> > + # Returns +true+ when the instance is a change involving a property
> > + # change.
> > + # [prop_changed?]
> > + # Ditto.
> > class DiffSummarize
> > alias prop_changed? prop_changed
>
> I don't want users to see prop_changed? alias.

I think it is odd and wonder it goes against what you intend to do.
The alias 'prop_changed?' is defined so as for users to use the Rubyish
method name, isn't it? Inversely, users aren't expected to use the original
method name, 'prop_changed', I think.

So, I corrected my patch based on this respect, not as asked by you. If it
is wrong, sorry.

Here attached the third edition of the patch. :-)

Thanks,

-nori

Index: subversion/bindings/swig/ruby/svn/client.rb
===================================================================
--- subversion/bindings/swig/ruby/svn/client.rb (revision 20223)
+++ subversion/bindings/swig/ruby/svn/client.rb (working copy)
@@ -30,6 +30,13 @@
     end
 
     PropListItem = ProplistItem
+ # Following methods are also available:
+ #
+ # [name]
+ # Returns an URI for the item concerned with the instance.
+ # [props]
+ # Returns a Hash of properties, such as
+ # <tt>{propname1 => propval1, propname2 => propval2, ...}</tt>.
     class PropListItem
       alias name node_name
       alias props prop_hash
@@ -158,6 +165,8 @@
       alias pdel propdel
       alias pd propdel
 
+ # Returns a value of a property, with +name+ attached to +target+,
+ # as a Hash such as <tt>{uri1 => value1, uri2 => value2, ...}</tt>.
       def propget(name, target, rev=nil, peg_rev=nil, recurse=true)
         rev ||= "HEAD"
         peg_rev ||= rev
@@ -167,6 +176,9 @@
       alias pget propget
       alias pg propget
 
+ # Returns list of properties attached to +target+ as an Array of
+ # Svn::Client::PropListItem.
+ # Paths and URIs are available as +target+.
       def proplist(target, rev=nil, peg_rev=nil, recurse=true)
         rev ||= "HEAD"
         peg_rev ||= rev
@@ -214,9 +226,13 @@
                          out_file, err_file, self)
       end
 
+ # Invokes block once for each item changed between <tt>path1</tt>
+ # at <tt>rev1</tt> and <tt>path2</tt> at <tt>rev2</tt>,
+ # and returns +nil+.
+ # +diff+ is an instance of Svn::Client::DiffSummarize.
       def diff_summarize(path1, rev1, path2, rev2,
                          recurse=true, ignore_ancestry=true,
- &block)
+ &block) # :yields: diff
         Client.diff_summarize(path1, rev1, path2, rev2,
                               recurse, ignore_ancestry, block, self)
       end
@@ -245,6 +261,7 @@
                           force, dry_run, options, self)
       end
       
+ # Returns a content of +path+ at +rev+ as a String.
       def cat(path, rev="HEAD", peg_rev=nil, output=nil)
         used_string_io = output.nil?
         output ||= StringIO.new
@@ -276,6 +293,7 @@
         Client.info(path_or_uri, rev, peg_rev, receiver, recurse, self)
       end
 
+ # Returns URL for +path+ as a String.
       def url_from_path(path)
         Client.url_from_path(path)
       end
@@ -284,6 +302,7 @@
         Client.uuid_from_path(path, adm, self)
       end
       
+ # Returns UUID for +url+ as a String.
       def uuid_from_url(url)
         Client.uuid_from_url(url, self)
       end
@@ -292,6 +311,20 @@
         Client.open_ra_session(url, self)
       end
       
+ # Scans revisions from +start_rev+ to +end_rev+ for each path in
+ # +paths+, invokes block once for each revision, and then returns
+ # +nil+.
+ #
+ # When +discover_changed_paths+ is +false+ or +nil+, +changed_paths+,
+ # the first block-argument, is +nil+. Otherwise, it is a Hash
+ # containing simple information associated with the revision,
+ # whose keys are paths and values are changes, such as
+ # <tt>{path1 => change1, path2 => change2, ...}</tt>,
+ # where each path is an absolute one in the repository and each
+ # change is a instance of Svn::Core::LogChangedPath.
+ # The rest of the block arguments, +rev+, +author+, +date+, and
+ # +message+ are the revision number, author, date, and the log
+ # message of that revision, respectively.
       def log(paths, start_rev, end_rev, limit,
               discover_changed_paths, strict_node_history,
               peg_rev=nil)
@@ -305,6 +338,9 @@
                     receiver, self)
       end
 
+ # Returns log messages, for commits affecting +paths+ from +start_rev+
+ # to +end_rev+, as an Array of String.
+ # You can use URIs as well as paths as +paths+.
       def log_message(paths, start_rev=nil, end_rev=nil)
         start_rev ||= "HEAD"
         end_rev ||= start_rev
@@ -339,12 +375,18 @@
       alias annotate blame
       alias ann annotate
       
+ # Returns a value of a revision property named +name+ for +uri+
+ # at +rev+, as a String.
+ # Both URLs and paths are avaiable as +uri+.
       def revprop(name, uri, rev)
         value, = revprop_get(name, uri, rev)
         value
       end
       alias rp revprop
       
+ # Returns a value of a revision property named +name+ for +uri+
+ # at +rev+, as an Array such as <tt>[value, rev]</tt>.
+ # Both URLs and paths are avaiable as +uri+.
       def revprop_get(name, uri, rev)
         result = Client.revprop_get(name, uri, rev, self)
         if result.is_a?(Array)
@@ -356,18 +398,26 @@
       alias rpget revprop_get
       alias rpg revprop_get
       
+ # Sets +value+ as a revision property named +name+ for +uri+ at +rev+.
+ # Both URLs and paths are avaiable as +uri+.
       def revprop_set(name, value, uri, rev, force=false)
         Client.revprop_set(name, value, uri, rev, force, self)
       end
       alias rpset revprop_set
       alias rps revprop_set
       
+ # Deletes a revision property, named +name+, for +uri+ at +rev+.
+ # Both URLs and paths are avaiable as +uri+.
       def revprop_del(name, uri, rev, force=false)
         Client.revprop_set(name, nil, uri, rev, force, self)
       end
       alias rpdel revprop_del
       alias rpd revprop_del
 
+ # Returns a list of revision properties set for +uri+ at +rev+,
+ # as an Array such as
+ # <tt>[{revprop1 => value1, revprop2 => value2, ...}, rev]</tt>.
+ # Both URLs and paths are avaiable as +uri+.
       def revprop_list(uri, rev)
         props, rev = Client.revprop_list(uri, rev, self)
         if props.has_key?(Svn::Core::PROP_REVISION_DATE)
@@ -392,8 +442,14 @@
         Client.ls3(path_or_uri, rev, peg_rev, recurse, self)
       end
 
+ # Invokes block once for each path below +path_or_uri+ at +rev+
+ # and returns +nil+.
+ # +path+ is a relative path from the +path_or_uri+.
+ # +dirent+ is an instance of Svn::Core::Dirent.
+ # +abs_path+ is an absolute path for +path_or_uri+ in the repository.
       def list(path_or_uri, rev, peg_rev=nil, recurse=false,
- dirent_fields=nil, fetch_locks=true, &block)
+ dirent_fields=nil, fetch_locks=true,
+ &block) # :yields: path, dirent, lock, abs_path
         dirent_fields ||= Core::DIRENT_ALL
         Client.list(path_or_uri, peg_rev, rev, recurse, dirent_fields,
                     fetch_locks, self, block)
@@ -511,37 +567,52 @@
       end
     end
 
+ # Following methods are also available:
+ #
+ # [path]
+ # Returns a path concerned with the instance.
+ # [prop_changed?]
+ # Returns +true+ when the instance is a change involving a property
+ # change.
     class DiffSummarize
       alias prop_changed? prop_changed
 
+ # Returns +true+ when the instance is a normal change.
       def kind_normal?
         summarize_kind == DIFF_SUMMARIZE_KIND_NORMAL
       end
 
+ # Returns +true+ when the instance is a change involving addition.
       def kind_added?
         summarize_kind == DIFF_SUMMARIZE_KIND_ADDED
       end
 
+ # Returns +true+ when the instance is a change involving modification.
       def kind_modified?
         summarize_kind == DIFF_SUMMARIZE_KIND_MODIFIED
       end
 
+ # Returns +true+ when the instance is a change involving deletion.
       def kind_deleted?
         summarize_kind == DIFF_SUMMARIZE_KIND_DELETED
       end
 
+ # Returns +true+ when the instance is a change made to no node.
       def node_kind_none?
         node_kind == Core::NODE_NONE
       end
 
+ # Returns +true+ when the instance is a change made to a file node.
       def node_kind_file?
         node_kind == Core::NODE_FILE
       end
 
+ # Returns +true+ when the instance is a change made to a directory node.
       def node_kind_dir?
         node_kind == Core::NODE_DIR
       end
 
+ # Returns +true+ when the instance is a change made to an unknown node.
       def node_kind_unknown?
         node_kind == Core::NODE_UNKNOWN
       end
Index: subversion/bindings/swig/ruby/svn/core.rb
===================================================================
--- subversion/bindings/swig/ruby/svn/core.rb (revision 20223)
+++ subversion/bindings/swig/ruby/svn/core.rb (working copy)
@@ -319,24 +319,39 @@
       end
     end
 
+ # Following methods are also available:
+ #
+ # [created_rev]
+ # Returns a revision at which the instance was last modified.
+ # [has_props]
+ # Returns true if the instance has properties.
+ # [last_author]
+ # Returns an author who last modified the instance.
+ # [size]
+ # Returns a size of the instance.
     class Dirent
+ # Returns +true+ when the instance is none.
       def none?
         kind == NODE_NONE
       end
 
+ # Returns +true+ when the instance is a directory.
       def directory?
         kind == NODE_DIR
       end
 
+ # Returns +true+ when the instance is a file.
       def file?
         kind == NODE_FILE
       end
 
+ # Returns +true+ when the instance is an unknown node.
       def unknown?
         kind == NODE_UNKNOWN
       end
 
       alias _time time
+ # Returns a Time when the instance was last changed.
       def time
         __time = _time
         __time && Time.from_apr_time(__time)
@@ -457,7 +472,20 @@
       end
     end
 
+ # Following methods are also available:
+ #
+ # [action]
+ # Returns an action taken to the path at the revision.
+ # [copyfrom_path]
+ # If the path was added at the revision by the copy action from
+ # another path at another revision, returns an original path.
+ # Otherwise, returns +nil+.
+ # [copyfrom_rev]
+ # If the path was added at the revision by the copy action from
+ # another path at another revision, returns an original revision.
+ # Otherwise, returns <tt>-1</tt>.
     class LogChangedPath
+ # Returns +true+ when the path is added by the copy action.
       def copied?
         Util.copy?(copyfrom_path, copyfrom_rev)
       end

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Fri Jun 23 00:49:32 2006

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