Merge pull request #54 from libgit2/tomdoc

TomDoc

lib/rugged/repository.rb

@@ -1,38 +1,78 @@
 module Rugged
+  # Repository is an interface into a Git repository on-disk. It's the primary
+  # interface between your app and the main Git objects Rugged makes available
+  # to you.
   class Repository
-
+    # Pretty formatting of a Repository.
+    #
+    # Returns a very pretty String.
     def inspect
       "#<Rugged::Repository:#{object_id} {path: #{path.inspect}}>"
     end
 
-    # Get the most recent commit from this repo
+    # Get the most recent commit from this repo.
     #
-    # Returns a Rugged::Commit object
+    # Returns a Rugged::Commit object.
     def last_commit
       self.lookup self.head.target
     end
 
+    # Walks over a set of commits using Rugged::Walker.
+    #
+    # from    - The String SHA1 to push onto Walker to begin our walk.
+    # sorting - The sorting order of the commits, as defined in the README.
+    # block   - A block that we pass into walker#each.
+    #
+    # Returns nothing if called with a block, otherwise returns an instance of
+    # Enumerable::Enumerator containing Rugged::Commit objects.
     def walk(from, sorting=Rugged::SORT_DATE, &block)
       walker = Rugged::Walker.new(self)
       walker.sorting(sorting)
       walker.push(from)
       walker.each(&block)
     end
 
+    # Find the HEAD of this repository.
+    #
+    # Returns a Reference.
     def head
       ref = Reference.lookup(self, "HEAD")
       ref.resolve
     end
 
+    # Look up a SHA1.
+    #
+    # Returns one of the four classes that inherit from Rugged::Object.
     def lookup(oid)
       Rugged::Object.lookup(self, oid)
     end
 
-    # Look up a single reference by name
+    # Look up a single reference by name.
+    #
+    # Example:
+    #
+    #   repo.ref 'refs/heads/master'
+    #   # => #<Rugged::Reference:2199125780 {name: "refs/heads/master",
+    #          target: "25b5d3b40c4eadda8098172b26c68cf151109799"}>
+    #
+    # Returns a Rugged::Reference.
     def ref(ref_name)
       Rugged::Reference.lookup(self, ref_name)
     end
 
+    # Retuns all the References that match a pattern.
+    #
+    # refs - A Regexp (or String) to search for. Optional.
+    #
+    # Examples:
+    #
+    #   # All refs
+    #   repo.refs
+    #
+    #   # All remote refs
+    #   repo.refs 'refs/remotes'
+    #
+    # Returns an Array of References.
     def refs(pattern = nil)
       r = []
       ref_names.each do |ref_name|
@@ -46,26 +86,39 @@ def refs(pattern = nil)
       r
     end
 
+    # The names of all the refs.
+    #
+    # Returns an Enumerable::Enumerator containing all the String ref names.
     def ref_names
       Rugged::Reference.each(self)
     end
 
+    # All of the tags in the repository.
+    #
+    # Returns an Enumerable::Enumerator containing all the String tag names.
     def tags(pattern="")
       Rugged::Tag.each(self, pattern)
     end
 
+    # All of the remotes in the repository.
+    #
+    # Returns an Enumerable::Enumerator containing all the String remote names.
     def remotes
       Rugged::Remote.each(self)
     end
 
+    # Get the content of a file at a specific revision.
+    #
+    # revision - The String SHA1.
+    # path     - The String file path.
+    #
+    # Returns a String.
     def file_at(revision, path)
       tree = Rugged::Commit.lookup(self, revision).tree
       subtree = tree.get_subtree(path)
       blob_data = subtree.get_entry(File.basename path)
       blob = Rugged::Blob.lookup(self, blob_data[:oid])
       blob.content
     end
-
   end
-
-end
+end

test/repo_test.rb

@@ -58,19 +58,82 @@
     rm_loose(oid)
   end
 
-  test "can use the builtin walk method" do
+  test "can walk in a block" do
     oid = "a4a7dce85cf63874e984719f4fdd239f5145052f"
     list = []
     @repo.walk(oid) { |c| list << c }
     assert list.map {|c| c.oid[0,5] }.join('.'), "a4a7d.c4780.9fd73.4a202.5b5b0.84960"
   end
 
+  test "can walk without a block" do
+    commits = @repo.walk('a4a7dce85cf63874e984719f4fdd239f5145052f')
+
+    assert commits.kind_of?(Enumerable)
+    assert commits.count > 0
+  end
+
+  test "can lookup an object" do
+    object = @repo.lookup("8496071c1b46c854b31185ea97743be6a8774479")
+
+    assert object.kind_of?(Rugged::Commit)
+  end
+
+  test "can find a ref" do
+    ref = @repo.ref('refs/heads/master')
+
+    assert ref.kind_of?(Rugged::Reference)
+    assert_equal 'refs/heads/master', ref.name
+  end
+
+  test "can return all refs" do
+    refs = @repo.refs
+
+    assert_equal 4, refs.length
+  end
+
+  test "can return all refs that match" do
+    refs = @repo.refs 'refs/heads'
+
+    assert_equal 2, refs.length
+  end
+
+  test "can return the names of all refs" do
+    refs = @repo.ref_names
+
+    refs.each {|name| assert name.kind_of?(String)}
+    assert_equal 4, refs.count
+  end
+
+  test "can return all tags" do
+    tags = @repo.tags
+
+    assert_equal 2, tags.count
+  end
+
+  test "can return all tags that match" do
+    tags = @repo.tags 'v0.9'
+
+    assert_equal 1, tags.count
+  end
+
+  test "can return all remotes" do
+    remotes = @repo.remotes
+
+    assert_equal 1, remotes.count
+  end
+
   test "can lookup head from repo" do
     head = @repo.head
     assert_equal "36060c58702ed4c2a40832c51758d5344201d89a", head.target
     assert_equal :direct, head.type
   end
 
+  test "can access a file" do
+    sha = '36060c58702ed4c2a40832c51758d5344201d89a'
+    content = @repo.file_at(sha, 'new.txt')
+    assert_equal "new file\n", content
+  end
+
   test "garbage collection methods don't crash" do
     Rugged::Repository.new(@path)
     ObjectSpace.garbage_collect