From 900691567e51bf95bb92d36951e2b7b79d2596cc Mon Sep 17 00:00:00 2001 From: Antonio Jesus Navarro Perez Date: Tue, 28 Feb 2017 15:09:15 +0100 Subject: improve git package documentation (fix #231) --- blame.go | 30 +++++++++++++++--------------- references.go | 13 ++++++++----- remote.go | 2 +- 3 files changed, 24 insertions(+), 21 deletions(-) diff --git a/blame.go b/blame.go index d16cf25..bf04570 100644 --- a/blame.go +++ b/blame.go @@ -13,17 +13,21 @@ 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 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. +// Blame returns a BlameResult that contains all the data needed to know the +// last author of each line of an specified file starting the history from +// a specified commit. 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: // @@ -33,12 +37,6 @@ type BlameResult struct { // 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. // @@ -98,8 +96,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 { diff --git a/references.go b/references.go index fe1d12b..338e2b7 100644 --- a/references.go +++ b/references.go @@ -10,15 +10,18 @@ import ( "github.com/sergi/go-diff/diffmatchpatch" ) -// References returns a References for the file at "path", the commits are -// sorted in commit order. It stops searching a branch for a file upon reaching -// the commit were the file was created. +// References returns a slice of Commits for the file at "path", starting from +// the commit provided that contains the file from the provided path. The last +// commit into the returned slice is the commit where the file was created. +// If the provided commit does not contains the specified path, a nil slice is +// returned. The commits are sorted in commit order, newer to older. // // Caveats: +// // - Moves and copies are not currently supported. +// // - Cherry-picks are not detected unless there are no commits between them and -// therefore can appear repeated in the list. -// (see git path-id for hints on how to fix this). +// therefore can appear repeated in the list. (see git path-id for hints on how to fix this). func References(c *object.Commit, path string) ([]*object.Commit, error) { var result []*object.Commit seen := make(map[plumbing.Hash]struct{}, 0) diff --git a/remote.go b/remote.go index fe7993c..4f034bb 100644 --- a/remote.go +++ b/remote.go @@ -32,7 +32,7 @@ func newRemote(s storage.Storer, c *config.RemoteConfig) *Remote { return &Remote{s: s, c: c} } -// Config return the config +// Config returns the RemoteConfig object used to instantiate this Remote func (r *Remote) Config() *config.RemoteConfig { return r.c } -- cgit From be7e1e6443633728559577363e83fabd56e65a36 Mon Sep 17 00:00:00 2001 From: Antonio Jesus Navarro Perez Date: Thu, 2 Mar 2017 10:48:26 +0100 Subject: Add full stops and keep implementation details as internal comments. --- blame.go | 15 ++++++++++----- references.go | 3 ++- remote.go | 4 ++-- 3 files changed, 14 insertions(+), 8 deletions(-) diff --git a/blame.go b/blame.go index bf04570..a503b62 100644 --- a/blame.go +++ b/blame.go @@ -13,13 +13,13 @@ import ( "srcd.works/go-git.v4/utils/diff" ) -// BlameResult represents the result of a Blame operation +// BlameResult represents the result of a Blame operation. type BlameResult struct { - // Path is the path of the File that we're blaming + // Path is the path of the File that we're blaming. Path string - // Rev is the hash of the specified Commit used to generate this result + // 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 contains every line with its authorship. Lines []*Line } @@ -82,6 +82,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 @@ -96,7 +101,7 @@ 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 is the email address of the last author that modified 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 diff --git a/references.go b/references.go index 338e2b7..68a54a6 100644 --- a/references.go +++ b/references.go @@ -21,7 +21,8 @@ import ( // - Moves and copies are not currently supported. // // - Cherry-picks are not detected unless there are no commits between them and -// therefore can appear repeated in the list. (see git path-id for hints on how to fix this). +// therefore can appear repeated in the list. (see git path-id for hints on how +// to fix this). func References(c *object.Commit, path string) ([]*object.Commit, error) { var result []*object.Commit seen := make(map[plumbing.Hash]struct{}, 0) diff --git a/remote.go b/remote.go index 4f034bb..580e6b0 100644 --- a/remote.go +++ b/remote.go @@ -22,7 +22,7 @@ import ( var NoErrAlreadyUpToDate = errors.New("already up-to-date") -// Remote represents a connection to a remote repository +// Remote represents a connection to a remote repository. type Remote struct { c *config.RemoteConfig s storage.Storer @@ -32,7 +32,7 @@ func newRemote(s storage.Storer, c *config.RemoteConfig) *Remote { return &Remote{s: s, c: c} } -// Config returns the RemoteConfig object used to instantiate this Remote +// Config returns the RemoteConfig object used to instantiate this Remote. func (r *Remote) Config() *config.RemoteConfig { return r.c } -- cgit From e408162066eddd16434adf1ec87aaa74aaff294a Mon Sep 17 00:00:00 2001 From: Antonio Jesus Navarro Perez Date: Thu, 2 Mar 2017 12:49:56 +0100 Subject: Simplify Blame documentation --- blame.go | 51 ++++++++++++++++++++++++++------------------------- 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/blame.go b/blame.go index a503b62..a88627f 100644 --- a/blame.go +++ b/blame.go @@ -23,32 +23,33 @@ type BlameResult struct { Lines []*Line } -// Blame returns a BlameResult that contains all the data needed to know the -// last author of each line of an specified file starting the history from -// a specified commit. 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. +// 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 -- cgit