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

[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-19 11:16:49 CEST

Hi,

I'm writing RDoc comments for the SWIG/Ruby bindings and present the
patch here. It is only for parts of classes and methods in svn/core.rb
and svn/client.rb, and far from complete for now. However, it has grown
large enough to be committed, I think.

I'll be happy if some reviews and comments are given, and more happy if
it is approved to be committed. :-)

# FYI: RDoc is a system for generating documentation from Ruby source files.
# By running '(cd subversion/bindings/swig/ruby; rdoc svn)', you will find
# HTML documents generated in subversion/bindings/swig/ruby/doc.

Thanks,

-nori

[[[
Add some RDoc comments to the SWIG/Ruby bindings.

* subversion/bindings/swig/ruby/svn/client.rb
  (Svn::Client::Context#cat,
  (Svn::Client::Context#diff_summarize,
   Svn::Client::Context#list,
   Svn::Client::Context#log,
   Svn::Client::Context#log_message,
   Svn::Client::Context#propget,
   Svn::Client::Context#proplist,
   Svn::Client::Context#revprop,
   Svn::Client::Context#revprop_del,
   Svn::Client::Context#revprop_get,
   Svn::Client::Context#revprop_list,
   Svn::Client::Context#revprop_set,
   Svn::Client::Context#url_from_path,
   Svn::Client::Context#uuid_from_url,
   Svn::Client::DiffSummarize,
   Svn::Client::PropListItem): Add RDoc comments.

* subversion/bindings/swig/ruby/svn/core.rb
  (Svn::Core::Dirent,
   Svn::Core::LogChangedPath): Add RDoc comments.
]]]

Index: subversion/bindings/swig/ruby/svn/client.rb
===================================================================
--- subversion/bindings/swig/ruby/svn/client.rb (revision 20165)
+++ subversion/bindings/swig/ruby/svn/client.rb (working copy)
@@ -30,6 +30,21 @@
     end
 
     PropListItem = ProplistItem
+ # Following methods are also available:
+ #
+ # [name]
+ # Returns an URI for the item concerned with the instance.
+ # [node_name]
+ # Ditto.
+ # [prop_hash]
+ # Returns a Hash of properties, such as
+ # <tt>{ propname1 => propval1, propname2 => propval2, ... }</tt>.
+ # [props]
+ # Ditto.
+ #
+ # Other methods are:
+ # * node_name=
+ # * prop_hash=
     class PropListItem
       alias name node_name
       alias props prop_hash
@@ -158,6 +173,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 +184,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 +234,13 @@
                          out_file, err_file, self)
       end
 
+ # Invokes block once for each item changed between <em>path1</em>
+ # at <em>rev1</em> and <em>path2</em> at <em>rev2</em>,
+ # 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 +269,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 +301,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 +310,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 +319,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 +346,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 +383,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 +406,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 +450,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 +575,62 @@
       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.
+ # [prop_changed?]
+ # Ditto.
+ #
+ # Other methods are:
+ # * node_kind
+ # * node_kind=
+ # * path=
+ # * prop_changed=
+ # * summarize_kind
+ # * summarize_kind=
     class DiffSummarize
       alias prop_changed? prop_changed
 
       def kind_normal?
+ # Returns _true_ when the instance is a normal change.
         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 20165)
+++ subversion/bindings/swig/ruby/svn/core.rb (working copy)
@@ -319,24 +319,47 @@
       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.
+ #
+ # Other methods are:
+ # * created_rev=
+ # * has_props=
+ # * kind
+ # * kind=
+ # * size=
+ # * time=
     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 +480,24 @@
       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 <em>-1</em>.
+ #
+ # Other methods are:
+ # * action=
+ # * copyfrom_rev=
     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 Mon Jun 19 11:17:53 2006

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.