From db6601f168162cca020c0f49e1bf2406db8ca4c3 Mon Sep 17 00:00:00 2001
From: Georg Seibt <seibt@fim.uni-passau.de>
Date: Thu, 20 Oct 2016 09:21:23 +0200
Subject: [PATCH] document BlameLine
---
.../fim/seibt/gitwrapper/repo/BlameLine.java | 89 ++++++++++++++++++-
1 file changed, 87 insertions(+), 2 deletions(-)
diff --git a/src/de/uni_passau/fim/seibt/gitwrapper/repo/BlameLine.java b/src/de/uni_passau/fim/seibt/gitwrapper/repo/BlameLine.java
index ef0b9ab..682e622 100644
--- a/src/de/uni_passau/fim/seibt/gitwrapper/repo/BlameLine.java
+++ b/src/de/uni_passau/fim/seibt/gitwrapper/repo/BlameLine.java
@@ -4,18 +4,58 @@ import java.io.File;
import java.util.Collections;
import java.util.Map;
+/**
+ * A line from a file with the associated 'git blame' information.
+ */
+@SuppressWarnings("WeakerAccess")
public class BlameLine {
+ /**
+ * The last commit to change the line.
+ */
public final Commit commit;
+ /**
+ * The line number of the line in the original file.
+ */
public final int originalLineNumber;
+
+ /**
+ * The line number of the line in the final file.
+ */
public final int finalLineNumber;
+ /**
+ * The file in the commit that the line is attributed to.
+ */
public final File file;
+
+ /**
+ * The actual line from the file.
+ */
public final String line;
+ /**
+ * Other (unrecognized) fields from the 'git blame' commit header.
+ */
public final Map<String, String> otherHeaderFields;
+ /**
+ * Constructs a new {@link BlameLine}.
+ *
+ * @param commit
+ * the last commit to change the line
+ * @param originalLineNumber
+ * the line number of the line in the original file
+ * @param finalLineNumber
+ * the line number of the line in the final file
+ * @param file
+ * the file in the commit that the line is attributed to
+ * @param line
+ * the actual line from the file
+ * @param otherHeaderFields
+ * other (unrecognized) fields from the 'git blame' commit header
+ */
private BlameLine(Commit commit, int originalLineNumber, int finalLineNumber, File file, String line,
Map<String, String> otherHeaderFields) {
@@ -27,16 +67,61 @@ public class BlameLine {
this.otherHeaderFields = otherHeaderFields;
}
+ /**
+ * Constructs a new {@link BlameLine}. This method is to be used when the 'git blame' parser in
+ * {@link Repository#parseBlameLines(String)} first reads the commit header for a commit.
+ *
+ * @param commit
+ * the last commit to change the line
+ * @param originalLineNumber
+ * the line number of the line in the original file
+ * @param finalLineNumber
+ * the line number of the line in the final file
+ * @param file
+ * the file in the commit that the line is attributed to
+ * @param line
+ * the actual line from the file
+ * @param otherHeaderFields
+ * other (unrecognized) fields from the 'git blame' commit header
+ * @return a {@link BlameLine} containing the given header fields
+ */
static BlameLine firstOccurrence(Commit commit, int originalLineNumber, int finalLineNumber, File file, String line,
Map<String, String> otherHeaderFields) {
- Map<String, String> other = otherHeaderFields.isEmpty() ? Collections.EMPTY_MAP : Collections.unmodifiableMap(otherHeaderFields);
+ Map<String, String> other;
+
+ if (otherHeaderFields.isEmpty()) {
+ other = Collections.emptyMap();
+ } else {
+ other = Collections.unmodifiableMap(otherHeaderFields);
+ }
+
return new BlameLine(commit, originalLineNumber, finalLineNumber, file, line, other);
}
+ /**
+ * Constructs a new {@link BlameLine}. This method is to be used when the 'git blame' parser encounters a line
+ * attributed to a commit whose header was previously read an packaged in a {@link BlameLine}. References to the
+ * header fields that are not line specific will be taken from {@code firstOccurrence} and stored in the returned
+ * {@link BlameLine}.
+ *
+ * @param firstOccurrence
+ * the {@link BlameLine} representing the first occurrence of the commit it contains
+ * @param originalLineNumber
+ * the line number of the line in the original file
+ * @param finalLineNumber
+ * the line number of the line in the final file
+ * @param line
+ * the actual line from the file
+ * @return a {@link BlameLine} containing the given header fields and references to the {@code firstOccurrence}
+ */
static BlameLine nextOccurrence(BlameLine firstOccurrence, int originalLineNumber, int finalLineNumber,
String line) {
- return new BlameLine(firstOccurrence.commit, originalLineNumber, finalLineNumber, firstOccurrence.file, line, firstOccurrence.otherHeaderFields);
+ Commit commit = firstOccurrence.commit;
+ File file = firstOccurrence.file;
+ Map<String, String> otherHeaderFields = firstOccurrence.otherHeaderFields;
+
+ return new BlameLine(commit, originalLineNumber, finalLineNumber, file, line, otherHeaderFields);
}
}
--
GitLab