Merge pull request #762 from MichaelMure/fix-comment

Fix a bunch of comments and documentations

6 files changed, 15 insertions, 13 deletions

diff --git a/bug/bug.go b/bug/bug.go
index 9d19a42c..48269a91 100644
--- a/bug/bug.go
+++ b/bug/bug.go
@@ -28,7 +28,7 @@ var def = dag.Definition{
 
 var ClockLoader = dag.ClockLoader(def)
 
-// Bug hold the data of a bug thread, organized in a way close to
+// Bug holds the data of a bug thread, organized in a way close to
 // how it will be persisted inside Git. This is the data structure
 // used to merge two different version of the same Bug.
 type Bug struct {
diff --git a/bug/bug_actions.go b/bug/bug_actions.go
index 420fb08a..c8239e41 100644
--- a/bug/bug_actions.go
+++ b/bug/bug_actions.go
@@ -22,13 +22,15 @@ func Push(repo repository.Repo, remote string) (string, error) {
 
 // Pull will do a Fetch + MergeAll
 // This function will return an error if a merge fail
-func Pull(repo repository.ClockedRepo, remote string, author identity.Interface) error {
+// Note: an author is necessary for the case where a merge commit is created, as this commit will
+// have an author and may be signed if a signing key is available.
+func Pull(repo repository.ClockedRepo, remote string, mergeAuthor identity.Interface) error {
 	_, err := Fetch(repo, remote)
 	if err != nil {
 		return err
 	}
 
-	for merge := range MergeAll(repo, remote, author) {
+	for merge := range MergeAll(repo, remote, mergeAuthor) {
 		if merge.Err != nil {
 			return merge.Err
 		}
@@ -43,7 +45,7 @@ func Pull(repo repository.ClockedRepo, remote string, author identity.Interface)
 // MergeAll will merge all the available remote bug
 // Note: an author is necessary for the case where a merge commit is created, as this commit will
 // have an author and may be signed if a signing key is available.
-func MergeAll(repo repository.ClockedRepo, remote string, author identity.Interface) <-chan entity.MergeResult {
+func MergeAll(repo repository.ClockedRepo, remote string, mergeAuthor identity.Interface) <-chan entity.MergeResult {
 	// no caching for the merge, we load everything from git even if that means multiple
 	// copy of the same entity in memory. The cache layer will intercept the results to
 	// invalidate entities if necessary.
@@ -54,7 +56,7 @@ func MergeAll(repo repository.ClockedRepo, remote string, author identity.Interf
 	go func() {
 		defer close(out)
 
-		results := dag.MergeAll(def, repo, identityResolver, remote, author)
+		results := dag.MergeAll(def, repo, identityResolver, remote, mergeAuthor)
 
 		// wrap the dag.Entity into a complete Bug
 		for result := range results {
diff --git a/bug/op_add_comment.go b/bug/op_add_comment.go
index 15e62226..8eb937cf 100644
--- a/bug/op_add_comment.go
+++ b/bug/op_add_comment.go
@@ -64,7 +64,7 @@ func (op *AddCommentOperation) Validate() error {
 	return nil
 }
 
-// UnmarshalJSON is a two step JSON unmarshalling
+// UnmarshalJSON is a two-steps JSON unmarshalling
 // This workaround is necessary to avoid the inner OpBase.MarshalJSON
 // overriding the outer op's MarshalJSON
 func (op *AddCommentOperation) UnmarshalJSON(data []byte) error {
diff --git a/bug/op_edit_comment.go b/bug/op_edit_comment.go
index a69cb599..4740f37b 100644
--- a/bug/op_edit_comment.go
+++ b/bug/op_edit_comment.go
@@ -101,7 +101,7 @@ func (op *EditCommentOperation) Validate() error {
 	return nil
 }
 
-// UnmarshalJSON is a two step JSON unmarshalling
+// UnmarshalJSON is two steps JSON unmarshalling
 // This workaround is necessary to avoid the inner OpBase.MarshalJSON
 // overriding the outer op's MarshalJSON
 func (op *EditCommentOperation) UnmarshalJSON(data []byte) error {
@@ -144,7 +144,7 @@ func NewEditCommentOp(author identity.Interface, unixTime int64, target entity.I
 	}
 }
 
-// Convenience function to apply the operation
+// EditComment is a convenience function to apply the operation
 func EditComment(b Interface, author identity.Interface, unixTime int64, target entity.Id, message string) (*EditCommentOperation, error) {
 	return EditCommentWithFiles(b, author, unixTime, target, message, nil)
 }
@@ -158,13 +158,13 @@ func EditCommentWithFiles(b Interface, author identity.Interface, unixTime int64
 	return editCommentOp, nil
 }
 
-// Convenience function to edit the body of a bug (the first comment)
+// EditCreateComment is a convenience function to edit the body of a bug (the first comment)
 func EditCreateComment(b Interface, author identity.Interface, unixTime int64, message string) (*EditCommentOperation, error) {
 	createOp := b.FirstOp().(*CreateOperation)
 	return EditComment(b, author, unixTime, createOp.Id(), message)
 }
 
-// Convenience function to edit the body of a bug (the first comment)
+// EditCreateCommentWithFiles is a convenience function to edit the body of a bug (the first comment)
 func EditCreateCommentWithFiles(b Interface, author identity.Interface, unixTime int64, message string, files []repository.Hash) (*EditCommentOperation, error) {
 	createOp := b.FirstOp().(*CreateOperation)
 	return EditCommentWithFiles(b, author, unixTime, createOp.Id(), message, files)
diff --git a/bug/snapshot.go b/bug/snapshot.go
index ce84cce1..d73e4bb6 100644
--- a/bug/snapshot.go
+++ b/bug/snapshot.go
@@ -26,7 +26,7 @@ type Snapshot struct {
 	Operations []Operation
 }
 
-// Return the Bug identifier
+// Id returns the Bug identifier
 func (snap *Snapshot) Id() entity.Id {
 	if snap.id == "" {
 		// simply panic as it would be a coding error (no id provided at construction)
@@ -35,7 +35,7 @@ func (snap *Snapshot) Id() entity.Id {
 	return snap.id
 }
 
-// Return the last time a bug was modified
+// EditTime returns the last time a bug was modified
 func (snap *Snapshot) EditTime() time.Time {
 	if len(snap.Operations) == 0 {
 		return time.Unix(0, 0)
diff --git a/bug/timeline.go b/bug/timeline.go
index a5ca4da5..4146db36 100644
--- a/bug/timeline.go
+++ b/bug/timeline.go
@@ -10,7 +10,7 @@ import (
 )
 
 type TimelineItem interface {
-	// ID return the identifier of the item
+	// Id return the identifier of the item
 	Id() entity.Id
 }