From 3ea66af17863121ec7dd84940d18f10cee7f4ee2 Mon Sep 17 00:00:00 2001
From: Joshua Peek <josh@joshpeek.com>
Date: Wed, 25 May 2011 10:39:05 -0500
Subject: [PATCH] Document Repository

---
 lib/linguist/repository.rb | 41 +++++++++++++++++++++++++++++++++-----
 1 file changed, 36 insertions(+), 5 deletions(-)

diff --git a/lib/linguist/repository.rb b/lib/linguist/repository.rb
index 8d9e0d96..f4a3e689 100644
--- a/lib/linguist/repository.rb
+++ b/lib/linguist/repository.rb
@@ -1,5 +1,10 @@
 module Linguist
   class Repository
+    # Public: Initialize a new Repository
+    #
+    # paths - A Hash of String path keys and Blob values.
+    #
+    # Returns a Repository
     def initialize(paths)
       @paths = paths
 
@@ -8,45 +13,71 @@ module Linguist
       @sizes = Hash.new { 0 }
     end
 
+    # Public: Lookup blob for path.
+    #
+    # Returns a Blob
     def [](path)
       @paths[path]
     end
 
-    def language
-      compute_stats
-      @language
-    end
-
+    # Public: Returns a breakdown of langauge stats.
+    #
+    # Examples
+    #
+    #   # => { Langauge['Ruby'] => 46319,
+    #          Langauge['JavaScript'] => 258 }
+    #
+    # Returns a Hash of Language keys and Integer size values.
     def languages
       compute_stats
       @sizes
     end
 
+    # Public: Get primary Language of repository.
+    #
+    # Returns a Language
+    def language
+      compute_stats
+      @language
+    end
+
+    # Public: Get the total size of the repository.
+    #
+    # Returns a byte size Integer
     def size
       compute_stats
       @size
     end
 
+    # Internal: Compute language breakdown for each blob in the Repository.
+    #
+    # Returns nothing
     def compute_stats
       return if @computed_stats
 
       @paths.each do |path, blob|
+        # Skip vendored or generated blobs
         next if blob.vendored? || blob.generated?
 
         language = blob.language
 
+        # Only include common langauges
         if language.common?
           @sizes[language] += blob.size
         end
       end
 
+      # Compute total size
       @size = @sizes.inject(0) { |s,(k,v)| s + v }
 
+      # Get primary language
       if primary = @sizes.max_by { |(_, size)| size }
         @language = primary[0]
       end
 
       @computed_stats = true
+
+      nil
     end
   end
 end