Merge branch 'master' of github.com:spgroup/groundhog

README.md

@@ -17,50 +17,99 @@ In order for it to behave like an Eclipse project, you'll need to install the Ma
 
 `$ mvn eclipse:eclipse`
 
-## Usage
-
 ### Generating the JAR
 
 Generate the JAR file for the Groundhog project.
 
-Eclipse users can go to `File > Export > Runnable Jar File` and enter the `CmdMain` class for the option "Launch Configuration".
+Eclipse users can go to `File > Export > Runnable JAR File` and enter the `CmdMain` class for the option "Launch Configuration".
 
-### Running Groundhog
+## Usage
 
-Search GitHub for projects matching "phonegap-facebook-plugin" and place the results (if any) in a folder called metrics:
+You can use Groundhog in two ways: as an executable JAR from the command line or as a library in your own Java project.
 
-```shell
-$ java -jar groundhog.jar -forge github -out metrics phonegap-facebook-plugin
+### Fetching Metadata
+
+Metadata is fetched from GitHub's API. In order to be able to fetch more objects, you need to  [obtain your GitHub API token](https://github.com/settings/applications) and use it in Groundhog.
+
+#### Project
+
+You can use Groundhog to fetch metadata on a list of projects that attend to a criteria
+
+```java
+// Create a GitHub search object
+Injector injector = Guice.createInjector(new SearchModule());
+SearchGitHub searchGitHub = injector.getInstance(SearchGitHub.class);
+
+// Search for projects named "opencv" starting in page 1 and stoping and going until the 3rd project
+List<Project> projects = searchGitHub.getProjects("opencv", 1, 3);
 ```
 
-### Running tests
+Alternatively, you can search for projects without setting the limiting point. In this case Groundhog will fetch projects until your API limit is exceeded.
 
+```java
+List<Project> projects = searchGitHub.getProjects("eclipse", 1, SearchGitHub.INFINITY)
 ```
-$ mvn test
+
+#### Issues
+
+Issues are objects that only make sense from a Project perspective.
+
+To fetch the Issues of a given project using Groundhog you should first create the Project and then tell Groundhog to hit the API and get the data.
+
+```java
+User user = new User("joyent");         // Create the User object
+Project pr = new Project(user, "node"); // Create the Project object
+
+// Tell Groundhog to fetch all Issues of that project and assign them the the Project object:
+List<Issue> issues = searchGitHub.getAllProjectIssues(pr);
+
+System.out.println("Listing 'em Issues...");
+for (Issue issue: issues) {
+  System.out.println(issue.getTitle());
+}
 ```
 
-## Info
+#### Milestones
 
-### Supported Forges
+Just like Issues, Groundhog lets you fetch the list of Milestones of a project, too.
 
-* GitHub
-* Google Code
-* SourceForge
+```java
+List<Milestone> milestones = searchGitHub.getAllProjectMilestones(pr);
+```
+
+#### Languages
+
+Software projects are often composed of more than one programming language. Groundhog lets you fetch the list of languages of a project among its LoC (lines of code) count.
+
+```java
+// Returns a List of Language objects for each language of project "pr"
+List<Language> languages = searchGitHub.fetchProjectLanguages(pr);
+```
 
-### Supported Programming Languages
+#### Contributors
 
-* Java, parsing only (more to be added later)
+You can also get the list of people who contributed to a project on GitHub:
 
-### Forge Search
+```java
+User user = new User("rails");
+Project project = new Project(user, "rails"); // project github.com/rails/rails
 
-* **GitHub**:
-Groundhog uses the [GitHub API v3] to search for repositories on GitHub
+List<User> contributors = searchGitHub.getAllProjectContributors(project);
+```
 
-* **Google Code**:
-to be written
+### Running Groundhog
 
-* **SourceForge**:
-to be written
+Search GitHub for projects matching "phonegap-facebook-plugin" and place the results (if any) in a folder called metrics:
+
+```shell
+$ java -jar groundhog.jar -forge github -out metrics phonegap-facebook-plugin
+```
+
+### Running tests
+
+```
+$ mvn test
+```
 
 ## Documentation
 
@@ -85,6 +134,8 @@ $ javadoc -d src/src/groundhog br.cin.ufpe.groundhog
 
 * Fernando Castor {[email protected]}
 
+* Jesus Silva {[email protected]}
+
 ## Contributions
 
 Want to contribute with code, documentation or bug report? That's great, check out the [Issues] page.

pom.xml

@@ -3,7 +3,7 @@
 	<modelVersion>4.0.0</modelVersion>
 	<groupId>br.ufpe.cin.groundhog</groupId>
 	<artifactId>groundhog</artifactId>
-	<version>0.0.1-SNAPSHOT</version>
+	<version>0.1.0</version>
 	<repositories>
 		<repository>
 			<id>jgit-repository</id>

src/java/main/br/ufpe/cin/groundhog/Commit.java

@@ -6,6 +6,7 @@
 /**
  * Represents a Commit object in Groundhog
  * @author Rodrigo Alves
+ * @since 0.0.1
  */
 public class Commit implements GitHubEntity {
 	@SerializedName("sha")
@@ -30,15 +31,8 @@ public class Commit implements GitHubEntity {
 
 	private int deletionsCount;
 
-	public Commit() {	
-	}
-
-	public Commit(String sha) {
-		this.sha = sha;
-	}
-
 	public Commit(String sha, Project project) {
-		this(sha);
+		this.sha = sha;
 		this.project = project;
 	}
 

src/java/main/br/ufpe/cin/groundhog/GroundhogException.java

@@ -1,9 +1,11 @@
 package br.ufpe.cin.groundhog;
 
 /**
- * The base {@link Exception} type for Groundhog. All Groundhog exceptions must extend this class.
+ * The base {@link Exception} type for Groundhog. All Groundhog exceptions must
+ * extend this class.
+ * 
  * @author fjsj, gustavopinto, Rodrigo Alves
- *
+ * @since 0.0.1
  */
 public class GroundhogException extends RuntimeException {
 	private static final long serialVersionUID = -3563928567447310893L;

src/java/main/br/ufpe/cin/groundhog/Language.java

@@ -1,12 +1,14 @@
 package br.ufpe.cin.groundhog;
 
 /**
- * Represents languages - an important set of components of a {@link Project} - in Groundhog.
- * This class is only important/meaningful in the context of Projects. As a representation of 
- * the programming language composition of such objects.
+ * Represents languages - an important set of components of a {@link Project} -
+ * in Groundhog. This class is only important/meaningful in the context of
+ * Projects. As a representation of the programming language composition of such
+ * objects.
  * 
  * @author Rodrigo Alves
- *
+ * @since 0.0.1
+ * 
  */
 public class Language implements Comparable<Language> {
 	private String name;
@@ -52,5 +54,7 @@ public int compareTo(Language o) {
 		return 0;
 	}
 
-
+	public String toString() {
+		return name;
+	}
 }

src/java/main/br/ufpe/cin/groundhog/License.java

@@ -2,6 +2,8 @@
 
 /**
  * Represents the license used in the project
+ * @author ghlp
+ * @since 0.0.1
  */
 public class License {