Merge pull request #295 from ajnavarro/improvement/package-git-doc

improve git package documentation (fix #231)

1 files changed, 41 insertions, 35 deletions

diff --git a/blame.go b/blame.go
index d16cf25..a88627f 100644
--- a/blame.go
+++ b/blame.go
@@ -13,44 +13,43 @@ import (
 	"srcd.works/go-git.v4/utils/diff"
 )
 
+// BlameResult represents the result of a Blame operation.
 type BlameResult struct {
-	Path  string
-	Rev   plumbing.Hash
+	// Path is the path of the File that we're blaming.
+	Path string
+	// Rev (Revision) is the hash of the specified Commit used to generate this result.
+	Rev plumbing.Hash
+	// Lines contains every line with its authorship.
 	Lines []*Line
 }
 
-// Blame returns the last commit that modified each line of a file in a
-// repository.
-//
-// The file to blame is identified by the input arguments: repo, commit and path.
-// The output is a slice of commits, one for each line in the file.
-//
-// Blaming a file is a two step process:
-//
-// 1. Create a linear history of the commits affecting a file. We use
-// revlist.New for that.
-//
-// 2. Then build a graph with a node for every line in every file in
-// the history of the file.
-//
-// Each node (line) holds the commit where it was introduced or
-// last modified. To achieve that we use the FORWARD algorithm
-// described in Zimmermann, et al. "Mining Version Archives for
-// Co-changed Lines", in proceedings of the Mining Software
-// Repositories workshop, Shanghai, May 22-23, 2006.
-//
-// Each node is assigned a commit: Start by the nodes in the first
-// commit. Assign that commit as the creator of all its lines.
-//
-// Then jump to the nodes in the next commit, and calculate the diff
-// between the two files. Newly created lines get
-// assigned the new commit as its origin. Modified lines also get
-// this new commit. Untouched lines retain the old commit.
-//
-// All this work is done in the assignOrigin function which holds all
-// the internal relevant data in a "blame" struct, that is not
-// exported.
+// Blame returns a BlameResult with the information about the last author of
+// each line from file `path` at commit `c`.
 func Blame(c *object.Commit, path string) (*BlameResult, error) {
+	// The file to blame is identified by the input arguments:
+	// commit and path. commit is a Commit object obtained from a Repository. Path
+	// represents a path to a specific file contained into the repository.
+	//
+	// Blaming a file is a two step process:
+	//
+	// 1. Create a linear history of the commits affecting a file. We use
+	// revlist.New for that.
+	//
+	// 2. Then build a graph with a node for every line in every file in
+	// the history of the file.
+	//
+	// Each node is assigned a commit: Start by the nodes in the first
+	// commit. Assign that commit as the creator of all its lines.
+	//
+	// Then jump to the nodes in the next commit, and calculate the diff
+	// between the two files. Newly created lines get
+	// assigned the new commit as its origin. Modified lines also get
+	// this new commit. Untouched lines retain the old commit.
+	//
+	// All this work is done in the assignOrigin function which holds all
+	// the internal relevant data in a "blame" struct, that is not
+	// exported.
+	//
 	// TODO: ways to improve the efficiency of this function:
 	// 1. Improve revlist
 	// 2. Improve how to traverse the history (example a backward traversal will
@@ -84,6 +83,11 @@ func Blame(c *object.Commit, path string) (*BlameResult, error) {
 		return nil, err
 	}
 
+	// Each node (line) holds the commit where it was introduced or
+	// last modified. To achieve that we use the FORWARD algorithm
+	// described in Zimmermann, et al. "Mining Version Archives for
+	// Co-changed Lines", in proceedings of the Mining Software
+	// Repositories workshop, Shanghai, May 22-23, 2006.
 	lines, err := newLines(finalLines, b.sliceGraph(len(b.graph)-1))
 	if err != nil {
 		return nil, err
@@ -98,8 +102,10 @@ func Blame(c *object.Commit, path string) (*BlameResult, error) {
 
 // Line values represent the contents and author of a line in BlamedResult values.
 type Line struct {
-	Author string // email address of the author of the line.
-	Text   string // original text of the line.
+	// Author is the email address of the last author that modified the line.
+	Author string
+	// Text is the original text of the line.
+	Text string
 }
 
 func newLine(author, text string) *Line {