Fix a bunch of comments and documentations

17 files changed, 43 insertions, 41 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
 }
 
diff --git a/cache/bug_cache.go b/cache/bug_cache.go
index a248e872..0e4611da 100644
--- a/cache/bug_cache.go
+++ b/cache/bug_cache.go
@@ -12,10 +12,10 @@ import (
 
 var ErrNoMatchingOp = fmt.Errorf("no matching operation found")
 
-// BugCache is a wrapper around a Bug. It provide multiple functions:
+// BugCache is a wrapper around a Bug. It provides multiple functions:
 //
 // 1. Provide a higher level API to use than the raw API from Bug.
-// 2. Maintain an up to date Snapshot available.
+// 2. Maintain an up-to-date Snapshot available.
 // 3. Deal with concurrency.
 type BugCache struct {
 	repoCache *RepoCache
@@ -235,7 +235,7 @@ func (c *BugCache) SetTitleRaw(author *IdentityCache, unixTime int64, title stri
 	return op, c.notifyUpdated()
 }
 
-// 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 (c *BugCache) EditCreateComment(body string) (*bug.EditCommentOperation, error) {
 	author, err := c.repoCache.GetUserIdentity()
 	if err != nil {
@@ -245,7 +245,7 @@ func (c *BugCache) EditCreateComment(body string) (*bug.EditCommentOperation, er
 	return c.EditCreateCommentRaw(author, time.Now().Unix(), body, nil)
 }
 
-// Convenience function to edit the body of a bug (the first comment)
+// EditCreateCommentRaw is a convenience function to edit the body of a bug (the first comment)
 func (c *BugCache) EditCreateCommentRaw(author *IdentityCache, unixTime int64, body string, metadata map[string]string) (*bug.EditCommentOperation, error) {
 	c.mu.Lock()
 	op, err := bug.EditCreateComment(c.bug, author.Identity, unixTime, body)
diff --git a/cache/repo_cache_bug.go b/cache/repo_cache_bug.go
index c019da68..bce01926 100644
--- a/cache/repo_cache_bug.go
+++ b/cache/repo_cache_bug.go
@@ -457,7 +457,7 @@ func (c *RepoCache) NewBugWithFiles(title string, message string, files []reposi
 	return c.NewBugRaw(author, time.Now().Unix(), title, message, files, nil)
 }
 
-// NewBugWithFilesMeta create a new bug with attached files for the message, as
+// NewBugRaw create a new bug with attached files for the message, as
 // well as metadata for the Create operation.
 // The new bug is written in the repository (commit)
 func (c *RepoCache) NewBugRaw(author *IdentityCache, unixTime int64, title string, message string, files []repository.Hash, metadata map[string]string) (*BugCache, *bug.CreateOperation, error) {
diff --git a/doc/queries.md b/doc/queries.md
index 3a38519b..358948eb 100644
--- a/doc/queries.md
+++ b/doc/queries.md
@@ -21,7 +21,7 @@ A few tips:
 You can filter bugs based on their status.
 
 | Qualifier       | Example                             |
-| ---             | ---                                 |
+|-----------------|-------------------------------------|
 | `status:open`   | `status:open` matches open bugs     |
 | `status:closed` | `status:closed` matches closed bugs |
 
@@ -30,7 +30,7 @@ You can filter bugs based on their status.
 You can filter based on the person who opened the bug.
 
 | Qualifier      | Example                                                                          |
-| ---            | ---                                                                              |
+|----------------|----------------------------------------------------------------------------------|
 | `author:QUERY` | `author:descartes` matches bugs opened by `René Descartes` or `Robert Descartes` |
 |                | `author:"rené descartes"` matches bugs opened by `René Descartes`                |
 
@@ -39,7 +39,7 @@ You can filter based on the person who opened the bug.
 You can filter based on the person who participated in any activity related to the bug (opened bug or added a comment).
 
 | Qualifier           | Example                                                                                            |
-| ---                 | ---                                                                                                |
+|---------------------|----------------------------------------------------------------------------------------------------|
 | `participant:QUERY` | `participant:descartes` matches bugs opened or commented by `René Descartes` or `Robert Descartes` |
 |                     | `participant:"rené descartes"` matches bugs opened or commented by `René Descartes`                |
 
@@ -48,7 +48,7 @@ You can filter based on the person who participated in any activity related to t
 You can filter based on the person who interacted with the bug.
 
 | Qualifier     | Example                                                                         |
-| ---           | ---                                                                             |
+|---------------|---------------------------------------------------------------------------------|
 | `actor:QUERY` | `actor:descartes` matches bugs edited by `René Descartes` or `Robert Descartes` |
 |               | `actor:"rené descartes"` matches bugs edited by `René Descartes`                |
 
@@ -59,7 +59,7 @@ You can filter based on the person who interacted with the bug.
 You can filter based on the bug's label.
 
 | Qualifier     | Example                                                                   |
-| ---           | ---                                                                       |
+|---------------|---------------------------------------------------------------------------|
 | `label:LABEL` | `label:prod` matches bugs with the label `prod`                           |
 |               | `label:"Good first issue"` matches bugs with the label `Good first issue` |
 
@@ -68,7 +68,7 @@ You can filter based on the bug's label.
 You can filter based on the bug's title.
 
 | Qualifier     | Example                                                                        |
-| ---           | ---                                                                            |
+|---------------|--------------------------------------------------------------------------------|
 | `title:TITLE` | `title:Critical` matches bugs with a title containing `Critical`               |
 |               | `title:"Typo in string"` matches bugs with a title containing `Typo in string` |
 
@@ -78,7 +78,7 @@ You can filter based on the bug's title.
 You can filter bugs based on the absence of something.
 
 | Qualifier  | Example                                |
-| ---        | ---                                    |
+|------------|----------------------------------------|
 | `no:label` | `no:label` matches bugs with no labels |
 
 ## Sorting
@@ -90,7 +90,7 @@ Note: to deal with differently-set clocks on distributed computers, `git-bug` us
 ### Sort by Id
 
 | Qualifier                  | Example                                               |
-| ---                        | ---                                                   |
+|----------------------------|-------------------------------------------------------|
 | `sort:id-desc`             | `sort:id-desc` will sort bugs by their descending Ids |
 | `sort:id` or `sort:id-asc` | `sort:id` will sort bugs by their ascending Ids       |
 
@@ -99,7 +99,7 @@ Note: to deal with differently-set clocks on distributed computers, `git-bug` us
 You can sort bugs by their creation time.
 
 | Qualifier                               | Example                                                             |
-| ---                                     | ---                                                                 |
+|-----------------------------------------|---------------------------------------------------------------------|
 | `sort:creation` or `sort:creation-desc` | `sort:creation` will sort bugs by their descending creation time    |
 | `sort:creation-asc`                     | `sort:creation-asc` will sort bugs by their ascending creation time |
 
@@ -108,6 +108,6 @@ You can sort bugs by their creation time.
 You can sort bugs by their edit time.
 
 | Qualifier                       | Example                                                             |
-| ---                             | ---                                                                 |
+|---------------------------------|---------------------------------------------------------------------|
 | `sort:edit` or `sort:edit-desc` | `sort:edit` will sort bugs by their descending last edition time    |
 | `sort:edit-asc`                 | `sort:edit-asc` will sort bugs by their ascending last edition time |
diff --git a/entity/dag/entity.go b/entity/dag/entity.go
index c4368514..ffdbe335 100644
--- a/entity/dag/entity.go
+++ b/entity/dag/entity.go
@@ -21,9 +21,9 @@ const editClockPattern = "%s-edit"
 
 // Definition hold the details defining one specialization of an Entity.
 type Definition struct {
-	// the name of the entity (bug, pull-request, ...)
+	// the name of the entity (bug, pull-request, ...), for human consumption
 	Typename string
-	// the Namespace in git (bugs, prs, ...)
+	// the Namespace in git references (bugs, prs, ...)
 	Namespace string
 	// a function decoding a JSON message into an Operation
 	OperationUnmarshaler func(author identity.Interface, raw json.RawMessage) (Operation, error)
@@ -121,7 +121,7 @@ func read(def Definition, repo repository.ClockedRepo, resolver identity.Resolve
 
 	// Next step is to:
 	// 1) read the operationPacks
-	// 2) make sure that the clocks causality respect the DAG topology.
+	// 2) make sure that clocks causality respect the DAG topology.
 
 	oppMap := make(map[repository.Hash]*operationPack)
 	var opsCount int
diff --git a/entity/dag/entity_actions.go b/entity/dag/entity_actions.go
index 2926e992..5b6e884d 100644
--- a/entity/dag/entity_actions.go
+++ b/entity/dag/entity_actions.go
@@ -89,7 +89,7 @@ func MergeAll(def Definition, repo repository.ClockedRepo, resolver identity.Res
 	return out
 }
 
-// merge perform a merge to make sure a local Entity is up to date.
+// merge perform a merge to make sure a local Entity is up-to-date.
 // See MergeAll for more details.
 func merge(def Definition, repo repository.ClockedRepo, resolver identity.Resolver, remoteRef string, author identity.Interface) entity.MergeResult {
 	id := entity.RefToId(remoteRef)
diff --git a/entity/dag/operation_pack.go b/entity/dag/operation_pack.go
index 5d74e13f..d825281b 100644
--- a/entity/dag/operation_pack.go
+++ b/entity/dag/operation_pack.go
@@ -81,7 +81,7 @@ func (opp *operationPack) Validate() error {
 	return nil
 }
 
-// Write write the OperationPack in git, with zero, one or more parent commits.
+// Write writes the OperationPack in git, with zero, one or more parent commits.
 // If the repository has a keypair able to sign (that is, with a private key), the resulting commit is signed with that key.
 // Return the hash of the created commit.
 func (opp *operationPack) Write(def Definition, repo repository.Repo, parentCommit ...repository.Hash) (repository.Hash, error) {
diff --git a/entity/id.go b/entity/id.go
index c8dbdb94..8f3dc25b 100644
--- a/entity/id.go
+++ b/entity/id.go
@@ -63,7 +63,7 @@ func (i Id) MarshalGQL(w io.Writer) {
 	_, _ = w.Write([]byte(`"` + i.String() + `"`))
 }
 
-// IsValid tell if the Id is valid
+// Validate tell if the Id is valid
 func (i Id) Validate() error {
 	// Special case to detect outdated repo
 	if len(i) == 40 {
diff --git a/entity/id_interleaved.go b/entity/id_interleaved.go
index 5423afee..0ce2ba00 100644
--- a/entity/id_interleaved.go
+++ b/entity/id_interleaved.go
@@ -22,7 +22,7 @@ import (
 //
 // A complete interleaved Id hold 50 characters for the primary and 14 for the
 // secondary, which give a key space of 36^50 for the primary (~6 * 10^77) and
-// 36^14 for the secondary (~6 * 10^21). This asymmetry assume a reasonable number
+// 36^14 for the secondary (~6 * 10^21). This asymmetry assumes a reasonable number
 // of secondary within a primary Entity, while still allowing for a vast key space
 // for the primary (that is, a globally merged database) with a low risk of collision.
 //
diff --git a/entity/refs.go b/entity/refs.go
index 070d4dba..6ba505b9 100644
--- a/entity/refs.go
+++ b/entity/refs.go
@@ -13,7 +13,7 @@ func RefsToIds(refs []string) []Id {
 	return ids
 }
 
-// RefsToIds parse a git reference and return the corresponding Entity's Id.
+// RefToId parse a git reference and return the corresponding Entity's Id.
 func RefToId(ref string) Id {
 	split := strings.Split(ref, "/")
 	return Id(split[len(split)-1])
diff --git a/identity/identity.go b/identity/identity.go
index ad5f1efd..0a7642af 100644
--- a/identity/identity.go
+++ b/identity/identity.go
@@ -381,9 +381,9 @@ func (i *Identity) NeedCommit() bool {
 //
 // To make sure that an Identity history can't be altered, a strict fast-forward
 // only policy is applied here. As an Identity should be tied to a single user, this
-// should work in practice but it does leave a possibility that a user would edit his
+// should work in practice, but it does leave a possibility that a user would edit his
 // Identity from two different repo concurrently and push the changes in a non-centralized
-// network of repositories. In this case, it would result in some of the repo accepting one
+// network of repositories. In this case, it would result in some repo accepting one
 // version and some other accepting another, preventing the network in general to converge
 // to the same result. This would create a sort of partition of the network, and manual
 // cleaning would be required.
@@ -396,9 +396,9 @@ func (i *Identity) NeedCommit() bool {
 // However, this approach leave the possibility, in the case of a compromised crypto keys,
 // of forging a new version with a bogus Lamport time to be inserted before a legit version,
 // invalidating the correct version and hijacking the Identity. There would only be a short
-// period of time where this would be possible (before the network converge) but I'm not
+// period of time when this would be possible (before the network converge) but I'm not
 // confident enough to implement that. I choose the strict fast-forward only approach,
-// despite it's potential problem with two different version as mentioned above.
+// despite its potential problem with two different version as mentioned above.
 func (i *Identity) Merge(repo repository.Repo, other *Identity) (bool, error) {
 	if i.Id() != other.Id() {
 		return false, errors.New("merging unrelated identities is not supported")
diff --git a/identity/interface.go b/identity/interface.go
index 5b14295b..c6e22e00 100644
--- a/identity/interface.go
+++ b/identity/interface.go
@@ -57,6 +57,6 @@ type Interface interface {
 	// Validate check if the Identity data is valid
 	Validate() error
 
-	// Indicate that the in-memory state changed and need to be commit in the repository
+	// NeedCommit indicate that the in-memory state changed and need to be committed in the repository
 	NeedCommit() bool
 }