.config/coc/extensions/coc-go-data/tools/pkg/mod/honnef.co/go/tools@v0.0.1-2020.1.5/stylecheck/doc.go

   1 package stylecheck
   2
   3 import "honnef.co/go/tools/lint"
   4
   5 var Docs = map[string]*lint.Documentation{
   6         "ST1000": {
   7                 Title: `Incorrect or missing package comment`,
   8                 Text: `Packages must have a package comment that is formatted according to
   9 the guidelines laid out in
  10 https://github.com/golang/go/wiki/CodeReviewComments#package-comments.`,
  11                 Since:      "2019.1",
  12                 NonDefault: true,
  13         },
  14
  15         "ST1001": {
  16                 Title: `Dot imports are discouraged`,
  17                 Text: `Dot imports that aren't in external test packages are discouraged.
  18
  19 The dot_import_whitelist option can be used to whitelist certain
  20 imports.
  21
  22 Quoting Go Code Review Comments:
  23
  24     The import . form can be useful in tests that, due to circular
  25     dependencies, cannot be made part of the package being tested:
  26
  27         package foo_test
  28
  29         import (
  30             "bar/testutil" // also imports "foo"
  31             . "foo"
  32         )
  33
  34     In this case, the test file cannot be in package foo because it
  35     uses bar/testutil, which imports foo. So we use the 'import .'
  36     form to let the file pretend to be part of package foo even though
  37     it is not. Except for this one case, do not use import . in your
  38     programs. It makes the programs much harder to read because it is
  39     unclear whether a name like Quux is a top-level identifier in the
  40     current package or in an imported package.`,
  41                 Since:   "2019.1",
  42                 Options: []string{"dot_import_whitelist"},
  43         },
  44
  45         "ST1003": {
  46                 Title: `Poorly chosen identifier`,
  47                 Text: `Identifiers, such as variable and package names, follow certain rules.
  48
  49 See the following links for details:
  50
  51 - https://golang.org/doc/effective_go.html#package-names
  52 - https://golang.org/doc/effective_go.html#mixed-caps
  53 - https://github.com/golang/go/wiki/CodeReviewComments#initialisms
  54 - https://github.com/golang/go/wiki/CodeReviewComments#variable-names`,
  55                 Since:      "2019.1",
  56                 NonDefault: true,
  57                 Options:    []string{"initialisms"},
  58         },
  59
  60         "ST1005": {
  61                 Title: `Incorrectly formatted error string`,
  62                 Text: `Error strings follow a set of guidelines to ensure uniformity and good
  63 composability.
  64
  65 Quoting Go Code Review Comments:
  66
  67     Error strings should not be capitalized (unless beginning with
  68     proper nouns or acronyms) or end with punctuation, since they are
  69     usually printed following other context. That is, use
  70     fmt.Errorf("something bad") not fmt.Errorf("Something bad"), so
  71     that log.Printf("Reading %s: %v", filename, err) formats without a
  72     spurious capital letter mid-message.`,
  73                 Since: "2019.1",
  74         },
  75
  76         "ST1006": {
  77                 Title: `Poorly chosen receiver name`,
  78                 Text: `Quoting Go Code Review Comments:
  79
  80     The name of a method's receiver should be a reflection of its
  81     identity; often a one or two letter abbreviation of its type
  82     suffices (such as "c" or "cl" for "Client"). Don't use generic
  83     names such as "me", "this" or "self", identifiers typical of
  84     object-oriented languages that place more emphasis on methods as
  85     opposed to functions. The name need not be as descriptive as that
  86     of a method argument, as its role is obvious and serves no
  87     documentary purpose. It can be very short as it will appear on
  88     almost every line of every method of the type; familiarity admits
  89     brevity. Be consistent, too: if you call the receiver "c" in one
  90     method, don't call it "cl" in another.`,
  91                 Since: "2019.1",
  92         },
  93
  94         "ST1008": {
  95                 Title: `A function's error value should be its last return value`,
  96                 Text:  `A function's error value should be its last return value.`,
  97                 Since: `2019.1`,
  98         },
  99
 100         "ST1011": {
 101                 Title: `Poorly chosen name for variable of type time.Duration`,
 102                 Text: `time.Duration values represent an amount of time, which is represented
 103 as a count of nanoseconds. An expression like 5 * time.Microsecond
 104 yields the value 5000. It is therefore not appropriate to suffix a
 105 variable of type time.Duration with any time unit, such as Msec or
 106 Milli.`,
 107                 Since: `2019.1`,
 108         },
 109
 110         "ST1012": {
 111                 Title: `Poorly chosen name for error variable`,
 112                 Text: `Error variables that are part of an API should be called errFoo or
 113 ErrFoo.`,
 114                 Since: "2019.1",
 115         },
 116
 117         "ST1013": {
 118                 Title: `Should use constants for HTTP error codes, not magic numbers`,
 119                 Text: `HTTP has a tremendous number of status codes. While some of those are
 120 well known (200, 400, 404, 500), most of them are not. The net/http
 121 package provides constants for all status codes that are part of the
 122 various specifications. It is recommended to use these constants
 123 instead of hard-coding magic numbers, to vastly improve the
 124 readability of your code.`,
 125                 Since:   "2019.1",
 126                 Options: []string{"http_status_code_whitelist"},
 127         },
 128
 129         "ST1015": {
 130                 Title: `A switch's default case should be the first or last case`,
 131                 Since: "2019.1",
 132         },
 133
 134         "ST1016": {
 135                 Title:      `Use consistent method receiver names`,
 136                 Since:      "2019.1",
 137                 NonDefault: true,
 138         },
 139
 140         "ST1017": {
 141                 Title: `Don't use Yoda conditions`,
 142                 Text: `Yoda conditions are conditions of the kind 'if 42 == x', where the
 143 literal is on the left side of the comparison. These are a common
 144 idiom in languages in which assignment is an expression, to avoid bugs
 145 of the kind 'if (x = 42)'. In Go, which doesn't allow for this kind of
 146 bug, we prefer the more idiomatic 'if x == 42'.`,
 147                 Since: "2019.2",
 148         },
 149
 150         "ST1018": {
 151                 Title: `Avoid zero-width and control characters in string literals`,
 152                 Since: "2019.2",
 153         },
 154
 155         "ST1019": {
 156                 Title: `Importing the same package multiple times`,
 157                 Text: `Go allows importing the same package multiple times, as long as
 158 different import aliases are being used. That is, the following
 159 bit of code is valid:
 160
 161 import (
 162     "fmt"
 163     fumpt "fmt"
 164     format "fmt"
 165     _ "fmt"
 166 )
 167
 168 However, this is very rarely done on purpose. Usually, it is a
 169 sign of code that got refactored, accidentally adding duplicate
 170 import statements. It is also a rarely known feature, which may
 171 contribute to confusion.
 172
 173 Do note that sometimes, this feature may be used
 174 intentionally (see for example
 175 https://github.com/golang/go/commit/3409ce39bfd7584523b7a8c150a310cea92d879d)
 176 – if you want to allow this pattern in your code base, you're
 177 advised to disable this check.`,
 178                 Since: "2020.1",
 179         },
 180
 181         "ST1020": {
 182                 Title: "The documentation of an exported function should start with the function's name",
 183                 Text: `Doc comments work best as complete sentences, which
 184 allow a wide variety of automated presentations. The first sentence
 185 should be a one-sentence summary that starts with the name being
 186 declared.
 187
 188 If every doc comment begins with the name of the item it describes,
 189 you can use the doc subcommand of the go tool and run the output
 190 through grep.
 191
 192 See https://golang.org/doc/effective_go.html#commentary for more
 193 information on how to write good documentation.`,
 194                 Since:      "2020.1",
 195                 NonDefault: true,
 196         },
 197
 198         "ST1021": {
 199                 Title: "The documentation of an exported type should start with type's name",
 200                 Text: `Doc comments work best as complete sentences, which
 201 allow a wide variety of automated presentations. The first sentence
 202 should be a one-sentence summary that starts with the name being
 203 declared.
 204
 205 If every doc comment begins with the name of the item it describes,
 206 you can use the doc subcommand of the go tool and run the output
 207 through grep.
 208
 209 See https://golang.org/doc/effective_go.html#commentary for more
 210 information on how to write good documentation.`,
 211                 Since:      "2020.1",
 212                 NonDefault: true,
 213         },
 214
 215         "ST1022": {
 216                 Title: "The documentation of an exported variable or constant should start with variable's name",
 217                 Text: `Doc comments work best as complete sentences, which
 218 allow a wide variety of automated presentations. The first sentence
 219 should be a one-sentence summary that starts with the name being
 220 declared.
 221
 222 If every doc comment begins with the name of the item it describes,
 223 you can use the doc subcommand of the go tool and run the output
 224 through grep.
 225
 226 See https://golang.org/doc/effective_go.html#commentary for more
 227 information on how to write good documentation.`,
 228                 Since:      "2020.1",
 229                 NonDefault: true,
 230         },
 231 }