From b11679bc80b115c61a5cdee8ff8b5f8f1f69533d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michael=20Mur=C3=A9?= Date: Thu, 10 Mar 2022 16:27:22 +0100 Subject: [PATCH] Fix a bunch of comments and documentations --- bug/bug.go | 2 +- bug/bug_actions.go | 10 ++++++---- bug/op_add_comment.go | 2 +- bug/op_edit_comment.go | 8 ++++---- bug/snapshot.go | 4 ++-- bug/timeline.go | 2 +- cache/bug_cache.go | 8 ++++---- cache/repo_cache_bug.go | 2 +- doc/queries.md | 20 ++++++++++---------- entity/dag/entity.go | 6 +++--- entity/dag/entity_actions.go | 2 +- entity/dag/operation_pack.go | 2 +- entity/id.go | 2 +- entity/id_interleaved.go | 2 +- entity/refs.go | 2 +- identity/identity.go | 8 ++++---- identity/interface.go | 2 +- 17 files changed, 43 insertions(+), 41 deletions(-) diff --git a/bug/bug.go b/bug/bug.go index 9d19a42cbdc3d58e440ba63975ca70f0d5bdeb36..48269a91cd7e73f165088a0b7237a20e07e07d32 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 420fb08af5c96230fc7ba199156d9a6337fd288f..c8239e419cee4b70798357878a08f549b072b50c 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 15e62226341e928a61bb9cd9cd5589f7baf7b237..8eb937cf8690034faffc4186631b95c50f0d2970 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 a69cb599e26fb89c869e32097520e31fb0a462be..4740f37b5a29c3676032c9114b8a2ec5ccdc6d6f 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 ce84cce125badfa68b3cc0d660b8a4934704d456..d73e4bb6795f023222c6c63a3d19084492adeab2 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 a5ca4da5a4a315654aaa42fc7f7c1072e35ce775..4146db36778d1e06939423736e90ecaf5ae1ecbb 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 a248e872a28cea48875696a2739e861e7c64dd2e..0e4611da172fc9c20151135fdaa49b9d2f90fff6 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 c019da68ae71e8a1aeafea0ede745eb610232198..bce019265b6dfecc2310fc7a155441331e2f8cf7 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 3a38519b686656256fe33e14d1a518df8671879e..358948eb6a57c9247ed1aedf1b07b83e522b388a 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 c43685146664ddfec9c24dae12a1251ec22cf895..ffdbe33528fd29a673c02c0fa4c393060ccdddb3 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 2926e992b2d6ade978bfe35b14071846f999c787..5b6e884d10900e1368475d60f01e7ca8a22fbd2c 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 5d74e13fe8abc6823d3df2ae82d2d590c0a7814e..d825281bfc19f00da8b98cd66f626c34179deb96 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 c8dbdb94d9ce4e497426ce1005bc8fb4c77524c6..8f3dc25bd6b6ec8bc9024c5ea202fb1780e4f9d4 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 5423afeed133b1dd908b533d0392d889fa81500a..0ce2ba00614dd5ecc7121233ee9b5b4791eb3005 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 070d4dbaab54a4f3f41320d66df8a5ae32765e8d..6ba505b96a5d3f3df9a56a7cb5a68c554228f3ce 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 ad5f1efd6386a603a036cbca80f9b7446e20f96c..0a7642af0777912356a5d300536eb6521700d480 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 5b14295b15d13c038a079df0925d0a5318b3275f..c6e22e0008dd81c107bff292078e3407c793468a 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 }