The documentation of an exported type should start with the type’s name GO-D5002
Documentation
Minor
2 months ago
—
a year old
comment on exported type DingtalkPayload should be of the form "DingtalkPayload ..." (with optional leading article)
35 IsAtAll bool `json:"isAtAll"`
36}
37
38// Refer: https://open-doc.dingtalk.com/docs/doc.htm?treeId=257&articleId=105735&docType=1 39type DingtalkPayload struct {
40 MsgType string `json:"msgtype"`
41 At DingtalkAtObject `json:"at"`comment on exported type DingtalkAtObject should be of the form "DingtalkAtObject ..." (with optional leading article)
29 SingleURL string `json:"singleURL"`
30}
31
32// Refer: https://open-doc.dingtalk.com/docs/doc.htm?treeId=257&articleId=105735&docType=1 33type DingtalkAtObject struct {
34 AtMobiles []string `json:"atMobiles"`
35 IsAtAll bool `json:"isAtAll"`comment on exported type DingtalkActionCard should be of the form "DingtalkActionCard ..." (with optional leading article)
19 DingtalkNotificationTitle = "Gogs Notification"
20)
21
22// Refer: https://open-doc.dingtalk.com/docs/doc.htm?treeId=257&articleId=105735&docType=1 23type DingtalkActionCard struct {
24 Title string `json:"title"`
25 Text string `json:"text"`comment on exported type Request should be of the form "Request ..." (with optional leading article)
101 EnableCookie bool
102}
103
104// HttpRequest provides more useful methods for requesting one url than http.Request.105type Request struct {
106 url string
107 req *http.Request
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 {
}