README.rdoc in fcoury-octopi-0.0.4 vs README.rdoc in fcoury-octopi-0.0.5

@@ -2,50 +2,58 @@
 
 Octopi is a Ruby interface to GitHub API v2 (http://develop.github.com). It's under early but active development and already works.
 
 == Example
 
-  include Octopi
+=== Users API
 
-  # user information
+Getting user information
+
   user = User.find("fcoury")
   puts "#{user.name} is being followed by #{user.followers.join(", ")} and following #{user.following.join(", ")}"
 
-  # the bang version of followers and following 
-  # fetches user object for each user, but is 
-  # a lot more expensive
+The bang methods `followers!` and `following!` retrieves a full User object for each user login returned, so it has to be used carefully.
+
   user.followers!.each do |u|
     puts "  - #{u.name} (#{u.login}) has #{u.public_repo_count} repo(s)"
   end
+  
+Searching for user
 
-  # search user
   users = User.find_all("silva")
   puts "#{users.size} users found for 'silva':"
   users.each do |u|
     puts "  - #{u.name}"
   end
 
-  # repository information
-  # to get all repos for user: user.repositories
+=== Repositories API
+
   repo = user.repository("octopi") # same as: Repository.find("fcoury", "octopi")
   puts "Repository: #{repo.name} - #{repo.description} (by #{repo.owner}) - #{repo.url}"
   puts "      Tags: #{repo.tags and repo.tags.map {|t| t.name}.join(", ")}"
+  
+Search:
 
-  # commits of a the repository
-  first_commit = repo.commits.first
-  puts "First commit: #{first_commit.id} - #{first_commit.message} - by #{first_commit.author['name']}"
-
-  # single commit information
-  # details is the same as: Commit.find(commit)
-  puts "Diff:"
-  first_commit.details.modified.each {|m| puts "#{m['filename']} DIFF: #{m['diff']}" }
-
-  # repository search
   repos = Repository.find_all("ruby", "git")
   puts "#{repos.size} repository(ies) with 'ruby' and 'git':"
   repos.each do |r|
     puts "  - #{r.name}"
   end
+  
+Issues API integrated into the Repository object:
+
+  issue = repo.issues.first
+  puts "First open issue: #{issue.number} - #{issue.title} - Created at: #{issue.created_at}"
+
+Commits API information from a Repository object:
+
+  first_commit = repo.commits.first
+  puts "First commit: #{first_commit.id} - #{first_commit.message} - by #{first_commit.author['name']}"
+  
+Single commit information:
+
+  puts "Diff:"
+  first_commit.details.modified.each {|m| puts "#{m['filename']} DIFF: #{m['diff']}" }
 
 == Author
 
 * Felipe Coury - http://felipecoury.com
 * HasMany.info blog - http://hasmany.info