From 5a4ca717a36f406c7259f7e6d7e09903488bc89e Mon Sep 17 00:00:00 2001
From: Florian Heck <florian.heck@hotmail.de>
Date: Thu, 20 Oct 2016 23:40:35 +0200
Subject: [PATCH] added missing documentation
---
.../fim/seibt/gitwrapper/repo/Branch.java | 13 +++++++++--
.../fim/seibt/gitwrapper/repo/Commit.java | 2 +-
.../seibt/gitwrapper/repo/DummyCommit.java | 2 +-
.../fim/seibt/gitwrapper/repo/GitWrapper.java | 14 +++++++----
.../fim/seibt/gitwrapper/repo/Reference.java | 11 +++++++++
.../fim/seibt/gitwrapper/repo/Repository.java | 23 +++++++------------
.../fim/seibt/gitwrapper/repo/Status.java | 11 +++++++++
7 files changed, 53 insertions(+), 23 deletions(-)
diff --git a/src/de/uni_passau/fim/seibt/gitwrapper/repo/Branch.java b/src/de/uni_passau/fim/seibt/gitwrapper/repo/Branch.java
index 8fcf1d5..f8bfa34 100644
--- a/src/de/uni_passau/fim/seibt/gitwrapper/repo/Branch.java
+++ b/src/de/uni_passau/fim/seibt/gitwrapper/repo/Branch.java
@@ -6,10 +6,19 @@ import java.util.Optional;
import java.util.function.Function;
import java.util.logging.Logger;
+/**
+ * A {@link Branch} is a named {@link Reference} to a git branch pointing to an {@link Commit}.
+ */
public class Branch extends Reference {
private static final Logger LOG = Logger.getLogger(Branch.class.getCanonicalName());
+ /**
+ * Constructs an object referencing an existing git branch.
+ *
+ * @param repo the repo this branch is part of
+ * @param name the branch name
+ */
Branch(Repository repo, String name) {
super(repo, name);
}
@@ -19,7 +28,7 @@ public class Branch extends Reference {
*
* @return true if the pull was successful
*/
- public Boolean pull() {
+ public boolean pull() {
if (!repo.checkout(this)) {
return false;
}
@@ -49,7 +58,7 @@ public class Branch extends Reference {
}
/**
- * Reruns the branch name
+ * Reruns the branch name.
*
* @return the branch name
*/
diff --git a/src/de/uni_passau/fim/seibt/gitwrapper/repo/Commit.java b/src/de/uni_passau/fim/seibt/gitwrapper/repo/Commit.java
index 8a0afed..1dd75d7 100644
--- a/src/de/uni_passau/fim/seibt/gitwrapper/repo/Commit.java
+++ b/src/de/uni_passau/fim/seibt/gitwrapper/repo/Commit.java
@@ -11,6 +11,7 @@ import java.util.regex.Pattern;
* A {@link Commit} made in a {@link Repository}.
*/
public class Commit extends Reference {
+
private static final Logger LOG = Logger.getLogger(Commit.class.getCanonicalName());
// since there is no porcelain format for this command, this regex is might depend on the git version
@@ -19,7 +20,6 @@ public class Commit extends Reference {
private static final Pattern COMMITTER_INFO = Pattern.compile("committer (.*?)<(.*?)> (\\d+) ([+-]\\d{4})\\n");
private static final Pattern EMPTY_LINE = Pattern.compile("^\\s*$", Pattern.MULTILINE);
-
private String message;
private String author;
diff --git a/src/de/uni_passau/fim/seibt/gitwrapper/repo/DummyCommit.java b/src/de/uni_passau/fim/seibt/gitwrapper/repo/DummyCommit.java
index 1b08225..5fc852d 100644
--- a/src/de/uni_passau/fim/seibt/gitwrapper/repo/DummyCommit.java
+++ b/src/de/uni_passau/fim/seibt/gitwrapper/repo/DummyCommit.java
@@ -60,6 +60,6 @@ public class DummyCommit extends Commit {
private void setterWarning() {
LOG.finest(() -> "Ignoring a setter call on the DummyCommit for " + repo);
- // TODO gets called often while parsing blame lines, maybe change level
+ // TODO gets called often while parsing blame lines
}
}
diff --git a/src/de/uni_passau/fim/seibt/gitwrapper/repo/GitWrapper.java b/src/de/uni_passau/fim/seibt/gitwrapper/repo/GitWrapper.java
index 245196c..e7942d9 100644
--- a/src/de/uni_passau/fim/seibt/gitwrapper/repo/GitWrapper.java
+++ b/src/de/uni_passau/fim/seibt/gitwrapper/repo/GitWrapper.java
@@ -1,7 +1,9 @@
package de.uni_passau.fim.seibt.gitwrapper.repo;
-import static de.uni_passau.fim.seibt.gitwrapper.process.ProcessExecutor.asList;
+import de.uni_passau.fim.seibt.gitwrapper.process.ProcessExecutor.ExecRes;
+import de.uni_passau.fim.seibt.gitwrapper.process.ToolNotWorkingException;
+import de.uni_passau.fim.seibt.gitwrapper.process.ToolWrapper;
import java.io.File;
import java.util.HashMap;
@@ -13,9 +15,7 @@ import java.util.logging.Logger;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
-import de.uni_passau.fim.seibt.gitwrapper.process.ProcessExecutor.ExecRes;
-import de.uni_passau.fim.seibt.gitwrapper.process.ToolNotWorkingException;
-import de.uni_passau.fim.seibt.gitwrapper.process.ToolWrapper;
+import static de.uni_passau.fim.seibt.gitwrapper.process.ProcessExecutor.asList;
/**
* A wrapper for executing git commands.
@@ -127,6 +127,12 @@ public class GitWrapper extends ToolWrapper {
return res.map(toRepo);
}
+ /**
+ * Imports an existing repository.
+ *
+ * @param directory the path to the repository
+ * @return the {@link Repository} if the import was successful or an empty {@link Optional} if there was an error
+ */
public Optional<Repository> importRepository(File directory) {
if (!isGitDir(directory)) {
return Optional.empty();
diff --git a/src/de/uni_passau/fim/seibt/gitwrapper/repo/Reference.java b/src/de/uni_passau/fim/seibt/gitwrapper/repo/Reference.java
index dbe5d11..55e6050 100644
--- a/src/de/uni_passau/fim/seibt/gitwrapper/repo/Reference.java
+++ b/src/de/uni_passau/fim/seibt/gitwrapper/repo/Reference.java
@@ -10,6 +10,11 @@ import java.util.function.Function;
import java.util.logging.Logger;
import java.util.stream.Collectors;
+/**
+ * A git object referencing a tree-ish object.
+ * @see Commit
+ * @see Branch
+ */
public abstract class Reference {
private static final Logger LOG = Logger.getLogger(Reference.class.getCanonicalName());
@@ -24,6 +29,12 @@ public abstract class Reference {
this.git = repo.getGit();
}
+ /**
+ * Returns the id of this reference. This can be a SHA1 hash or a reference name, but must resolve to a
+ * valid git object.
+ *
+ * @return the id
+ */
public String getId() {
return id;
}
diff --git a/src/de/uni_passau/fim/seibt/gitwrapper/repo/Repository.java b/src/de/uni_passau/fim/seibt/gitwrapper/repo/Repository.java
index 0de2761..5fbf4e8 100644
--- a/src/de/uni_passau/fim/seibt/gitwrapper/repo/Repository.java
+++ b/src/de/uni_passau/fim/seibt/gitwrapper/repo/Repository.java
@@ -1,5 +1,8 @@
package de.uni_passau.fim.seibt.gitwrapper.repo;
+import de.uni_passau.fim.seibt.gitwrapper.process.ProcessExecutor.ExecRes;
+import org.apache.commons.io.FileUtils;
+
import java.io.File;
import java.io.IOException;
import java.nio.file.Path;
@@ -7,24 +10,12 @@ import java.nio.file.Paths;
import java.time.Instant;
import java.time.OffsetDateTime;
import java.time.ZoneId;
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.Collections;
-import java.util.HashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.NoSuchElementException;
-import java.util.Objects;
-import java.util.Optional;
-import java.util.Scanner;
+import java.util.*;
import java.util.function.Function;
import java.util.logging.Level;
import java.util.logging.Logger;
import java.util.stream.Collectors;
-import de.uni_passau.fim.seibt.gitwrapper.process.ProcessExecutor.ExecRes;
-import org.apache.commons.io.FileUtils;
-
/**
* A git {@link Repository}.
*/
@@ -159,7 +150,7 @@ public class Repository {
}
/**
- * Returns the merge commits in this repository.
+ * Returns a list of all merge commits in this repository.
*
* @return the merge commits
*/
@@ -195,7 +186,7 @@ public class Repository {
/**
* Returns the {@link Commit} currently pointed at by <code>HEAD</code>.
*
- * @return the <code>HEAD</code> commit
+ * @return the <code>HEAD</code> commit or an empty {@link Optional} if there was an error
*/
public Optional<Commit> getCurrentHEAD() {
Optional<ExecRes> revParse = git.exec(dir, "rev-parse", "HEAD");
@@ -219,6 +210,8 @@ public class Repository {
* @param id
* the ID for the {@link Commit}
* @return the {@link Commit}
+ *
+ * @see #getCommit(String)
*/
Commit getCommitUnchecked(String id) {
return commits.computeIfAbsent(id, theID -> new Commit(this, theID));
diff --git a/src/de/uni_passau/fim/seibt/gitwrapper/repo/Status.java b/src/de/uni_passau/fim/seibt/gitwrapper/repo/Status.java
index 6b4113d..1249a81 100644
--- a/src/de/uni_passau/fim/seibt/gitwrapper/repo/Status.java
+++ b/src/de/uni_passau/fim/seibt/gitwrapper/repo/Status.java
@@ -11,8 +11,19 @@ import java.util.regex.Pattern;
public class Status {
private static final Pattern STATUS_ENTRY = Pattern.compile("(.?.) (?:.*? )?(.*?)\0");
+ /**
+ * The commit, this {@link Status} is based on.
+ */
public final String id;
+
+ /**
+ * A map of files which were changed since the last commit (with id {@link #id}) and their status codes.
+ */
public final Map<Path, String> changed;
+
+ /**
+ * A map of files which are in an unmerged state and their status codes.
+ */
public final Map<Path, String> unmerged;
/**
--
GitLab