Expand comments in cmd/checker/ and gerrit/
Change-Id: Idc46b9449020ad83f1fffdaf9e97086622fbfaf3
diff --git a/cmd/checker/checker.go b/cmd/checker/checker.go
index f57ebc7..25c49ba 100644
--- a/cmd/checker/checker.go
+++ b/cmd/checker/checker.go
@@ -37,9 +37,10 @@
todo chan *gerrit.PendingChecksInfo
}
+// checkerScheme is the scheme by which we are registered in the Gerrit server.
const checkerScheme = "fmt"
-// ListCheckers returns all the checkers that conform to our scheme.
+// ListCheckers returns all the checkers for our scheme.
func (gc *gerritChecker) ListCheckers() ([]*gerrit.CheckerInfo, error) {
c, err := gc.server.GetPath("a/plugins/checks/checkers/")
if err != nil {
@@ -65,7 +66,8 @@
return filtered, nil
}
-// PostChecker modifies a checker.
+// PostChecker creates or changes a checker. It sets up a checker on
+// the given repo, for the given language.
func (gc *gerritChecker) PostChecker(repo, language string, update bool) (*gerrit.CheckerInfo, error) {
hash := sha1.New()
hash.Write([]byte(repo))
@@ -102,6 +104,7 @@
return &out, nil
}
+// checkerLanguage extracts the language to check for from a checker UUID.
func checkerLanguage(uuid string) (string, bool) {
uuid = strings.TrimPrefix(uuid, checkerScheme+":")
fields := strings.Split(uuid, "-")
@@ -111,6 +114,8 @@
return fields[0], true
}
+// NewGerritChecker creates a server that periodically checks a gerrit
+// server for pending checks.
func NewGerritChecker(server *gerrit.Server) (*gerritChecker, error) {
gc := &gerritChecker{
server: server,
@@ -121,8 +126,11 @@
return gc, nil
}
+// errIrrelevant is a marker error value used for checks that don't apply for a change.
var errIrrelevant = errors.New("irrelevant")
+// checkChange checks a (change, patchset) for correct formatting in the given language. It returns
+// a list of complaints, or the errIrrelevant error if there is nothing to do.
func (c *gerritChecker) checkChange(changeID string, psID int, language string) ([]string, error) {
ch, err := c.server.GetChange(changeID, strconv.Itoa(psID))
if err != nil {
@@ -179,6 +187,8 @@
return msgs, nil
}
+// pendingLoop periodically contacts gerrit to find new checks to
+// execute. It should be executed in a goroutine.
func (c *gerritChecker) pendingLoop() {
for {
pending, err := c.server.PendingChecksByScheme(checkerScheme)
@@ -202,6 +212,8 @@
}
}
+// Serve runs the serve loop, executing formatters for checks that
+// need it.
func (gc *gerritChecker) Serve() {
for p := range gc.todo {
// TODO: parallelism?.
@@ -211,6 +223,7 @@
}
}
+// status encodes the checker states.
type status int
var (
@@ -231,6 +244,7 @@
}[s]
}
+// executeCheck executes the pending checks specified in the argument.
func (gc *gerritChecker) executeCheck(pc *gerrit.PendingChecksInfo) error {
log.Println("checking", pc)
diff --git a/gerrit/server.go b/gerrit/server.go
index 5072eb1..6d835ea 100644
--- a/gerrit/server.go
+++ b/gerrit/server.go
@@ -26,6 +26,7 @@
"strings"
)
+// Server represents a single Gerrit host.
type Server struct {
UserAgent string
URL url.URL
@@ -38,6 +39,7 @@
BasicAuth string
}
+// New creates a Gerrit Server for the given URL.
func New(u url.URL) *Server {
g := &Server{
URL: u,
@@ -50,6 +52,7 @@
return g
}
+// GetPath runs a Get on the given path.
func (g *Server) GetPath(p string) ([]byte, error) {
u := g.URL
u.Path = path.Join(u.Path, p)
@@ -60,6 +63,7 @@
return g.Get(&u)
}
+// Do runs a HTTP request against the remote server.
func (g *Server) Do(req *http.Request) (*http.Response, error) {
req.Header.Set("User-Agent", g.UserAgent)
if g.BasicAuth != "" {
@@ -76,6 +80,7 @@
return g.Client.Do(req)
}
+// Get runs a HTTP GET request on the given URL.
func (g *Server) Get(u *url.URL) ([]byte, error) {
req, err := http.NewRequest("GET", u.String(), nil)
if err != nil {
@@ -93,6 +98,7 @@
return ioutil.ReadAll(rep.Body)
}
+// PostPath posts the given data onto a path.
func (g *Server) PostPath(p string, contentType string, content []byte) ([]byte, error) {
u := g.URL
u.Path = path.Join(u.Path, p)
@@ -186,6 +192,7 @@
return out, nil
}
+// PendingChecks returns the checks pending for the given checker.
func (s *Server) PendingChecks(checkerUUID string) ([]*PendingChecksInfo, error) {
u := s.URL
@@ -208,6 +215,7 @@
return out, nil
}
+// PostCheck posts a single check result onto a change.
func (s *Server) PostCheck(changeID string, psID int, input *CheckInput) (*CheckInfo, error) {
body, err := json.Marshal(input)
if err != nil {
