Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

chore: improved documentation #16

Merged
merged 1 commit into from
Jun 18, 2019
Merged

chore: improved documentation #16

merged 1 commit into from
Jun 18, 2019

Conversation

glouvigny
Copy link
Member

No description provided.

@glouvigny glouvigny requested a review from a team as a code owner June 14, 2019 17:01
@glouvigny glouvigny self-assigned this Jun 14, 2019
aeddi
aeddi suggested changes Jun 18, 2019
View reviewed changes
accesscontroller/default.go Outdated
@@ -8,6 +9,8 @@ import (
type Default struct {
}

// Checks whether a given identity can append an entry to the log.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No dot at the end of the sentence (consistency)

accesscontroller/default.go Outdated
@@ -1,3 +1,4 @@
// Default access controller for IPFS Log
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe you should make it clear that it's a noop access controller? (in addition to the CanAppend comment)

entry/entry.go Outdated
@@ -1,18 +1,17 @@
// Entry structure for IPFS Log and its associated methods.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No dot at the end of the sentence (consistency)

entry/entry.go Outdated
@@ -298,42 +304,44 @@ func Verify(identity identityprovider.Interface, entry *Entry) error {
return nil
}

func ToMultihash(ipfsInstance io.IpfsServices, entry *Entry) (cid.Cid, error) {
if entry == nil {
// Gets the multihash of an Entry.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No dot at the end of the sentence (consistency)

entry/entry.go Outdated

return entryCID, err
}

func FromMultihash(ipfs io.IpfsServices, hash cid.Cid, provider identityprovider.Interface) (*Entry, error) {
// Creates an Entry from a hash.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No dot at the end of the sentence (consistency)

entry/entry.go
return true
}
}

return false
}

// Finds an entry's children from an Array of entries.
// Returns entry's children as an Array up to the last know child.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No dot at the end of the sentence (consistency)

entry/sorting/sorting.go Outdated
@@ -1,15 +1,19 @@
package log // import "berty.tech/go-ipfs-log/log"
// Sorting utilities for slices of Entries
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/utilities/helpers/ ?

errmsg/errmsg.go Outdated
@@ -1,6 +1,7 @@
// Error messages used by the Go version of IPFS Log.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No dot at the end of the sentence (consistency)

identityprovider/identity.go Outdated
@@ -1,3 +1,4 @@
// Default identity provider for IPFS Log and OrbitDB.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No dot at the end of the sentence (consistency)

keystore/keystore.go Outdated
@@ -1,3 +1,4 @@
// A local key manager for OrbitDB and IPFS Log.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No dot at the end of the sentence (consistency)

@aeddi
Copy link
Member

aeddi commented Jun 18, 2019 •
edited by unfurl-links bot
Loading

In addition to the corrections above, golang official linter specifies a format for the comment of exported method / fuction / attributes: https://github.com/golang/lint

Running golint ./... gives me the following output:

log.go:1:1: package comment should be of the form "Package ipfslog ..."
log.go:23:6: exported type JSONLog should have comment or be unexported
log.go:28:6: exported type Log should have comment or be unexported
log.go:40:6: exported type LogOptions should have comment or be unexported
log.go:270:6: exported type IteratorOptions should have comment or be unexported
log.go:278:1: exported method Log.Iterator should have comment or be unexported
log.go:327:1: comment on exported method Log.Join should be of the form "Join ..."
log.go:494:1: comment on exported method Log.ToMultihash should be of the form "ToMultihash ..."
log.go:504:1: comment on exported function NewFromMultihash should be of the form "NewFromMultihash ..."
log.go:554:1: comment on exported function NewFromEntryHash should be of the form "NewFromEntryHash ..."
log.go:584:1: comment on exported function NewFromJSON should be of the form "NewFromJSON ..."
log.go:615:1: comment on exported function NewFromEntry should be of the form "NewFromEntry ..."
log.go:645:1: comment on exported method Log.Values should be of the form "Values ..."
log.go:656:1: comment on exported method Log.ToJSON should be of the form "ToJSON ..."
log.go:673:1: comment on exported method Log.Heads should be of the form "Heads ..."
log_io.go:16:6: exported type FetchOptions should have comment or be unexported
accesscontroller/default.go:1:1: package comment should be of the form "Package accesscontroller ..."
accesscontroller/default.go:9:6: exported type Default should have comment or be unexported
accesscontroller/default.go:12:1: comment on exported method Default.CanAppend should be of the form "CanAppend ..."
accesscontroller/interface.go:8:6: exported type Interface should have comment or be unexported
entry/entry.go:1:1: package comment should be of the form "Package entry ..."
entry/entry.go:21:6: exported type Entry should have comment or be unexported
entry/entry.go:33:6: exported type Hashable should have comment or be unexported
entry/entry.go:129:1: comment on exported function CreateEntry should be of the form "CreateEntry ..."
entry/entry.go:269:1: comment on exported method Entry.Verify should be of the form "Verify ..."
entry/entry.go:307:1: comment on exported method Entry.ToMultihash should be of the form "ToMultihash ..."
entry/entry.go:370:1: comment on exported method Entry.Equals should be of the form "Equals ..."
entry/entry.go:375:1: exported method Entry.IsParent should have comment or be unexported
entry/entry.go:385:1: comment on exported function FindChildren should be of the form "FindChildren ..."
entry/entry_io.go:12:6: exported type FetchOptions should have comment or be unexported
entry/entry_io.go:21:1: comment on exported function FetchParallel should be of the form "FetchParallel ..."
entry/entry_io.go:35:1: comment on exported function FetchAll should be of the form "FetchAll ..."
entry/entry_map.go:7:1: comment on exported type OrderedMap should be of the form "OrderedMap ..." (with optional leading article)
entry/entry_map.go:12:1: comment on exported function NewOrderedMap should be of the form "NewOrderedMap ..."
entry/entry_map.go:19:1: comment on exported function NewOrderedMapFromEntries should be of the form "NewOrderedMapFromEntries ..."
entry/entry_map.go:34:1: comment on exported method OrderedMap.Merge should be of the form "Merge ..."
entry/entry_map.go:47:1: comment on exported method OrderedMap.Copy should be of the form "Copy ..."
entry/entry_map.go:60:1: comment on exported method OrderedMap.Get should be of the form "Get ..."
entry/entry_map.go:71:1: comment on exported method OrderedMap.UnsafeGet should be of the form "UnsafeGet ..."
entry/entry_map.go:78:1: comment on exported method OrderedMap.Set should be of the form "Set ..."
entry/entry_map.go:83:1: exported method OrderedMap.Slice should have comment or be unexported
entry/entry_map.go:94:1: comment on exported method OrderedMap.Delete should be of the form "Delete ..."
entry/entry_map.go:99:1: comment on exported method OrderedMap.Keys should be of the form "Keys ..."
entry/entry_map.go:104:1: comment on exported method OrderedMap.SortKeys should be of the form "SortKeys ..."
entry/entry_map.go:109:1: comment on exported method OrderedMap.Sort should be of the form "Sort ..."
entry/entry_map.go:114:1: comment on exported method OrderedMap.Len should be of the form "Len ..."
entry/entry_map.go:119:1: comment on exported method OrderedMap.At should be of the form "At ..."
entry/lamportclock.go:13:6: exported type LamportClock should have comment or be unexported
entry/lamportclock.go:18:1: comment on exported method LamportClock.Tick should be of the form "Tick ..."
entry/lamportclock.go:28:1: comment on exported method LamportClock.Merge should be of the form "Merge ..."
entry/lamportclock.go:38:1: comment on exported method LamportClock.Compare should be of the form "Compare ..."
entry/lamportclock.go:52:1: comment on exported function NewLamportClock should be of the form "NewLamportClock ..."
entry/utils.go:10:1: exported function Difference should have comment or be unexported
entry/utils.go:91:1: exported function FindHeads should have comment or be unexported
entry/sorting/sorting.go:1:1: package comment should be of the form "Package sorting ..."
entry/sorting/sorting.go:15:1: exported function SortByClocks should have comment or be unexported
entry/sorting/sorting.go:25:1: exported function SortByClockID should have comment or be unexported
entry/sorting/sorting.go:38:1: exported function First should have comment or be unexported
entry/sorting/sorting.go:42:1: exported function FirstWriteWins should have comment or be unexported
entry/sorting/sorting.go:48:1: exported function LastWriteWins should have comment or be unexported
entry/sorting/sorting.go:60:1: exported function NoZeroes should have comment or be unexported
entry/sorting/sorting.go:71:1: exported function Reverse should have comment or be unexported
entry/sorting/sorting.go:78:1: exported function Compare should have comment or be unexported
entry/sorting/sorting.go:87:1: exported function Sort should have comment or be unexported
errmsg/errmsg.go:1:1: package comment should be of the form "Package errmsg ..."
errmsg/errmsg.go:5:6: exported type Error should have comment or be unexported
errmsg/errmsg.go:10:2: exported const IPFSNotDefined should have comment (or a comment on this block) or be unexported
identityprovider/identities.go:17:6: exported type Identities should have comment or be unexported
identityprovider/identities.go:23:15: should replace errors.New(fmt.Sprintf(...)) with fmt.Errorf(...)
identityprovider/identities.go:35:1: exported method Identities.Sign should have comment or be unexported
identityprovider/identities.go:49:1: comment on exported method Identities.Verify should be of the form "Verify ..."
identityprovider/identities.go:73:1: comment on exported method Identities.CreateIdentity should be of the form "CreateIdentity ..."
identityprovider/identities.go:143:1: comment on exported method Identities.VerifyIdentity should be of the form "VerifyIdentity ..."
identityprovider/identities.go:172:1: comment on exported function CreateIdentity should be of the form "CreateIdentity ..."
identityprovider/identities.go:184:1: comment on exported function IsSupported should be of the form "IsSupported ..."
identityprovider/identities.go:191:1: comment on exported function AddIdentityProvider should be of the form "AddIdentityProvider ..."
identityprovider/identities.go:202:1: comment on exported function RemoveIdentityProvider should be of the form "RemoveIdentityProvider ..."
identityprovider/identity.go:1:1: package comment should be of the form "Package identityprovider ..."
identityprovider/identity.go:14:6: exported type IdentitySignature should have comment or be unexported
identityprovider/identity.go:19:6: exported type CborIdentitySignature should have comment or be unexported
identityprovider/identity.go:24:6: exported type Identity should have comment or be unexported
identityprovider/identity.go:32:6: exported type CborIdentity should have comment or be unexported
identityprovider/identity.go:39:1: exported method Identity.Filtered should have comment or be unexported
identityprovider/identity.go:48:1: exported method Identity.GetPublicKey should have comment or be unexported
identityprovider/identity.go:103:1: exported method Identity.ToCborIdentity should have comment or be unexported
identityprovider/identity.go:112:1: exported method CborIdentity.ToIdentity should have comment or be unexported
identityprovider/identity.go:132:1: exported method IdentitySignature.ToCborIdentitySignatures should have comment or be unexported
identityprovider/identity.go:139:1: exported method CborIdentitySignature.ToIdentitySignatures should have comment or be unexported
identityprovider/interface.go:5:6: exported type CreateIdentityOptions should have comment or be unexported
identityprovider/interface.go:13:6: exported type Interface should have comment or be unexported
identityprovider/orbitdb.go:11:6: exported type OrbitDBIdentityProvider should have comment or be unexported
identityprovider/orbitdb.go:15:1: comment on exported method OrbitDBIdentityProvider.VerifyIdentity should be of the form "VerifyIdentity ..."
identityprovider/orbitdb.go:20:1: comment on exported function NewOrbitDBIdentityProvider should be of the form "NewOrbitDBIdentityProvider ..."
identityprovider/orbitdb.go:27:1: comment on exported method OrbitDBIdentityProvider.GetID should be of the form "GetID ..."
identityprovider/orbitdb.go:45:1: comment on exported method OrbitDBIdentityProvider.SignIdentity should be of the form "SignIdentity ..."
identityprovider/orbitdb.go:49:15: should replace errors.New(fmt.Sprintf(...)) with fmt.Errorf(...)
identityprovider/orbitdb.go:59:15: should replace errors.New(fmt.Sprintf(...)) with fmt.Errorf(...)
identityprovider/orbitdb.go:65:1: comment on exported method OrbitDBIdentityProvider.Sign should be of the form "Sign ..."
identityprovider/orbitdb.go:80:1: comment on exported method OrbitDBIdentityProvider.GetType should be of the form "GetType ..."
io/io.go:1:1: package comment should be of the form "Package io ..."
io/io.go:16:1: exported function SetDebug should have comment or be unexported
io/io.go:20:1: exported function WriteCBOR should have comment or be unexported
io/io.go:38:1: exported function ReadCBOR should have comment or be unexported
io/service.go:7:1: comment on exported type IpfsServices should be of the form "IpfsServices ..." (with optional leading article)
keystore/interface.go:5:6: exported type Interface should have comment or be unexported
keystore/keystore.go:1:1: package comment should be of the form "Package keystore ..."
keystore/keystore.go:14:6: exported type Keystore should have comment or be unexported
keystore/keystore.go:19:1: exported method Keystore.Sign should have comment or be unexported
keystore/keystore.go:23:1: exported method Keystore.Verify should have comment or be unexported
keystore/keystore.go:36:1: exported function NewKeystore should have comment or be unexported
keystore/keystore.go:48:1: exported method Keystore.HasKey should have comment or be unexported
keystore/keystore.go:65:1: exported method Keystore.CreateKey should have comment or be unexported
keystore/keystore.go:86:1: exported method Keystore.GetKey should have comment or be unexported
test/identities.go:9:1: exported function MustDecodeHexString should have comment or be unexported
test/identities.go:29:1: exported function NewIdentityDataStore should have comment or be unexported
test/utils.go:24:1: exported function NewMemoryServices should have comment or be unexported
test/logcreator/logcreator.go:12:6: exported type CreatedLog should have comment or be unexported
test/logcreator/logcreator.go:88:1: exported function CreateLogWithSixteenEntries should have comment or be unexported
test/logcreator/logcreator.go:148:1: exported function CreateLogWithHundredEntries should have comment or be unexported
GitHub
[mirror] This is a linter for Go source code. Contribute to golang/lint development by creating an account on GitHub.

@glouvigny glouvigny force-pushed the glouvigny/doc branch 3 times, most recently from 05ac952 to 7ded735 Compare June 18, 2019 12:37
@glouvigny glouvigny merged commit dc7dfdc into master Jun 18, 2019
@glouvigny glouvigny deleted the glouvigny/doc branch June 20, 2019 11:40
@github-actions
Copy link

🎉 This PR is included in version 1.0.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@aeddi aeddi aeddi approved these changes

Assignees

@glouvigny glouvigny

Labels
released
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@glouvigny @aeddi