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