Documentation of an exported function should start with the function’s name GO-D5001
Documentation
Minor
2 months ago
—
2 years old
comment on exported method HasApiError should be of the form "HasApiError ..."
96 return c.User.ID
97}
98
99// HasError returns true if error occurs in form validation.100func (c *Context) HasApiError() bool {
101 hasErr, ok := c.Data["HasError"]
102 if !ok {comment on exported method APIFormat should be of the form "APIFormat ..."
91 return r.loadAttributes(x)
92}
93
94// This method assumes some fields assigned with values: 95// Required - Publisher
96func (r *Release) APIFormat() *api.Release {
97 return &api.Release{comment on exported function GetMilestoneByRepoID should be of the form "GetMilestoneByRepoID ..."
164 return m, nil
165}
166
167// GetWebhookByRepoID returns the milestone in a repository.168func GetMilestoneByRepoID(repoID, id int64) (*Milestone, error) {
169 return getMilestoneByRepoID(x, repoID, id)
170}comment on exported function DeleteDeploykey should be of the form "DeleteDeploykey ..."
96 c.JSON(http.StatusCreated, convert.ToDeployKey(apiLink, key))
97}
98
99// https://github.com/gogs/go-gogs-client/wiki/Repositories-Deploy-Keys#remove-a-deploy-key100func DeleteDeploykey(c *context.APIContext) {
101 if err := database.DeleteDeployKey(c.User, c.ParamsInt64(":id")); err != nil {
102 if database.IsErrKeyAccessDenied(err) {comment on exported function CreateDeployKey should be of the form "CreateDeployKey ..."
77 }
78}
79
80// https://github.com/gogs/go-gogs-client/wiki/Repositories-Deploy-Keys#add-a-new-deploy-key 81func CreateDeployKey(c *context.APIContext, form api.CreateKeyOption) {
82 content, err := database.CheckPublicKeyString(form.Key)
83 if err != nil {
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 function tries to summon a cybernetically enhanced duck
func SummonDucks() {
}
Recommended
package main
// SummonDucks tries to summon a cybernetically enhanced duck
func SummonDucks() {
}