The documentation of an exported type should start with the type’s name GO-D5002
Documentation
Minor
a month ago
—
10 months old
comment on exported type Wordfilter should be of the form "Wordfilter ..." (with optional leading article)
302 Username string // sql: `username`
303}
304
305// table DBPREFIXwordfilters306type Wordfilter struct {
307 ID int `json:"id"` // sql: `id`
308 BoardDirs *string `json:"boards"` // sql: `board_dirs`comment on exported type UsernameBan should be of the form "UsernameBan ..." (with optional leading article)
296 IsDeleted bool // sql: `is_deleted`
297}
298
299// table: DBPREFIXusername_ban300type UsernameBan struct {
301 filenameOrUsernameBanBase
302 Username string // sql: `username`comment on exported type Thread should be of the form "Thread ..." (with optional leading article)
283 IsActive bool `json:"-"` // sql: `is_active`
284}
285
286// table: DBPREFIXthreads287type Thread struct {
288 ID int // sql: `id`
289 BoardID int // sql: `board_id`comment on exported type Staff should be of the form "Staff ..." (with optional leading article)
272 Data string // sql: `data`
273}
274
275// DBPREFIXstaff276type Staff struct {
277 ID int // sql: `id`
278 Username string // sql: `username`comment on exported type LoginSession should be of the form "LoginSession ..." (with optional leading article)
264 Hidden bool // sql: `hidden`
265}
266
267// table: DBPREFIXsessions268type LoginSession struct {
269 ID int // sql: `id`
270 StaffID int // sql: `staff_id`
Description
Doc comments work best as complete sentences, which allow a wide variety of automated presentations. The first sentence should be a one-sentence summary that starts with the name being declared.
If every doc comment begins with the name of the item it describes, you can use the doc subcommand of the go tool and run the output through grep.
See https://golang.org/doc/effective_go.html#commentary for more information on how to write good documentation.
Bad practice
package main
// This struct represents an cybernetically enhanced duck
type Duck struct {
}
Recommended
package main
// Duck represents an cybernetically enhanced duck
type Duck struct {
}