client,docs: finalize errors.go comments

add final dots everywhere as recommended by go style guides and preferred by @degville adjust docs/error-kinds.go to that clarify to use docs/error-kinds.go and that the direction of sync is from code to forum for error kinds.
0dysseas · Aug 5, 2020 · 9bdb524 · 9bdb524
1 parent 1fd9fb4
commit 9bdb524
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 37 deletions.
diff --git a/client/errors.go b/client/errors.go
@@ -25,16 +25,17 @@ package client
 // error kind const value doc comments here have a non-default,
 // specialized style (to help docs/error-kind.go):
 //
-// // ErrorKind...: DESCRIPTION [no final dot]
+// // ErrorKind...: DESCRIPTION .
 //
+// Note the mandatory dot at the end.
 // `code-like` quoting should be used when meaningful.
 
-// Error kinds. Keep in sync with: https://forum.snapcraft.io/t/using-the-rest-api/18603#heading--errors
+// Error kinds. Keep https://forum.snapcraft.io/t/using-the-rest-api/18603#heading--errors in sync using doc/error-kinds.go.
 const (
 	// ErrorKindTwoFactorRequired: the client needs to retry the
-	// `login` command including an OTP
+	// `login` command including an OTP.
 	ErrorKindTwoFactorRequired = "two-factor-required"
-	// ErrorKindTwoFactorFailed: the OTP provided wasn't recognised
+	// ErrorKindTwoFactorFailed: the OTP provided wasn't recognised.
 	ErrorKindTwoFactorFailed = "two-factor-failed"
 	// ErrorKindLoginRequired: the requested operation cannot be
 	// performed without an authenticated user. This is the kind
@@ -45,44 +46,44 @@ const (
 	// `value` of the error is an object with a key per failed field
 	// and a list of the failures on each field.
 	ErrorKindInvalidAuthData = "invalid-auth-data"
-	// ErrorKindTermsNotAccepted: deprecated, do not document
+	// ErrorKindTermsNotAccepted: deprecated, do not document.
 	ErrorKindTermsNotAccepted = "terms-not-accepted"
-	// ErrorKindNoPaymentMethods: deprecated, do not document
+	// ErrorKindNoPaymentMethods: deprecated, do not document.
 	ErrorKindNoPaymentMethods = "no-payment-methods"
-	// ErrorKindPaymentDeclined: deprecated, do not document
+	// ErrorKindPaymentDeclined: deprecated, do not document.
 	ErrorKindPaymentDeclined = "payment-declined"
 	// ErrorKindPasswordPolicy: provided password doesn't meet
-	// system policy
+	// system policy.
 	ErrorKindPasswordPolicy = "password-policy"
 
 	// ErrorKindSnapAlreadyInstalled: the requested snap is
-	// already installed
+	// already installed.
 	ErrorKindSnapAlreadyInstalled = "snap-already-installed"
-	// ErrorKindSnapNotInstalled: the requested snap is not installed
+	// ErrorKindSnapNotInstalled: the requested snap is not installed.
 	ErrorKindSnapNotInstalled = "snap-not-installed"
-	// ErrorKindSnapNotFound: the requested snap couldn't be found
+	// ErrorKindSnapNotFound: the requested snap couldn't be found.
 	ErrorKindSnapNotFound = "snap-not-found"
-	// ErrorKindAppNotFound: the requested app couldn't be found
+	// ErrorKindAppNotFound: the requested app couldn't be found.
 	ErrorKindAppNotFound = "app-not-found"
-	// ErrorKindSnapLocal: cannot perform operation on local snap
+	// ErrorKindSnapLocal: cannot perform operation on local snap.
 	ErrorKindSnapLocal = "snap-local"
 	// ErrorKindSnapNeedsDevMode: the requested snap needs devmode
-	// to be installed
+	// to be installed.
 	ErrorKindSnapNeedsDevMode = "snap-needs-devmode"
 	// ErrorKindSnapNeedsClassic: the requested snap needs classic
-	// confinement to be installed
+	// confinement to be installed.
 	ErrorKindSnapNeedsClassic = "snap-needs-classic"
 	// ErrorKindSnapNeedsClassicSystem: the requested snap can't
-	// be installed on the current non-classic system
+	// be installed on the current non-classic system.
 	ErrorKindSnapNeedsClassicSystem = "snap-needs-classic-system"
-	// ErrorKindSnapNotClassic: snap not compatible with classic mode
+	// ErrorKindSnapNotClassic: snap not compatible with classic mode.
 	ErrorKindSnapNotClassic = "snap-not-classic"
 	// ErrorKindNoUpdateAvailable: the requested snap does not
-	// have an update available
+	// have an update available.
 	ErrorKindNoUpdateAvailable = "snap-no-update-available"
 
 	// ErrorKindRevisionNotAvailable: no snap revision available
-	// as specified
+	// as specified.
 	ErrorKindRevisionNotAvailable = "snap-revision-not-available"
 	// ErrorKindChannelNotAvailable: no snap revision on specified
 	// channel. The `value` of the error is a rich object with
@@ -102,41 +103,41 @@ const (
 	ErrorKindChangeConflict = "snap-change-conflict"
 
 	// ErrorKindNotSnap: the given snap or directory does not
-	// look like a snap
+	// look like a snap.
 	ErrorKindNotSnap = "snap-not-a-snap"
 
-	// ErrorKindNetworkTimeout: a timeout occurred during the request
+	// ErrorKindNetworkTimeout: a timeout occurred during the request.
 	ErrorKindNetworkTimeout = "network-timeout"
 
-	// ErrorKindDNSFailure: DNS not responding
+	// ErrorKindDNSFailure: DNS not responding.
 	ErrorKindDNSFailure = "dns-failure"
 
 	// ErrorKindInterfacesUnchanged: the requested interfaces'
-	// operation would have no effect
+	// operation would have no effect.
 	ErrorKindInterfacesUnchanged = "interfaces-unchanged"
 
-	// ErrorKindBadQuery: a bad query was provided
+	// ErrorKindBadQuery: a bad query was provided.
 	ErrorKindBadQuery = "bad-query"
 	// ErrorKindConfigNoSuchOption: the given configuration option
-	// does not exist
+	// does not exist.
 	ErrorKindConfigNoSuchOption = "option-not-found"
 
-	// ErrorKindAssertionNotFound: assertion can not be found
+	// ErrorKindAssertionNotFound: assertion can not be found.
 	ErrorKindAssertionNotFound = "assertion-not-found"
 
-	// ErrorKindUnsuccessful: snapctl command was unsuccessful
+	// ErrorKindUnsuccessful: snapctl command was unsuccessful.
 	ErrorKindUnsuccessful = "unsuccessful"
 
-	// ErrorKindAuthCancelled: authentication was cancelled by the user
+	// ErrorKindAuthCancelled: authentication was cancelled by the user.
 	ErrorKindAuthCancelled = "auth-cancelled"
 )
 
 // Maintenance error kinds.
 // These are used only inside the maintenance field of responses.
-// Keep in sync with: https://forum.snapcraft.io/t/using-the-rest-api/18603#heading--maint-errors
+// Keep https://forum.snapcraft.io/t/using-the-rest-api/18603#heading--maint-errors in sync using doc/error-kinds.go.
 const (
-	// ErrorKindDaemonRestart: daemon is restarting
+	// ErrorKindDaemonRestart: daemon is restarting.
 	ErrorKindDaemonRestart = "daemon-restart"
-	// ErrorKindSystemRestart: system is restarting
+	// ErrorKindSystemRestart: system is restarting.
 	ErrorKindSystemRestart = "system-restart"
 )
diff --git a/docs/error-kinds.go b/docs/error-kinds.go
@@ -68,12 +68,8 @@ func main() {
 				doc = strings.Replace(doc, "\n", " ", -1)
 				doc = strings.Replace(doc, "  ", " ", -1)
 				doc = strings.TrimSpace(doc)
-				doc1 := strings.TrimSuffix(doc, ".")
-				if doc1 != doc {
-					if strings.Index(doc1, ". ") == -1 {
-						fmt.Fprintf(os.Stderr, "unexpected dot at the end %q for %s\n", doc, name)
-					}
-					doc = doc1
+				if !strings.HasSuffix(doc, ".") {
+					fmt.Fprintf(os.Stderr, "expected dot at the end %q for %s\n", doc, name)
 				}
 				if strings.HasPrefix(doc, "deprecated") {
 					// skip