internal/gophers: add missing documentation
This is a step towards improving the usability of this package.
Use myself as an example of the types of queries that GetPerson
accepts.
Updates golang/go#27631
Change-Id: I3f4d497eb237958c652e51e03fd2459f0f9df8ef
Reviewed-on: https://go-review.googlesource.com/c/build/+/195064
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
diff --git a/internal/gophers/gophers.go b/internal/gophers/gophers.go
index 90cd677..d4f6256 100644
--- a/internal/gophers/gophers.go
+++ b/internal/gophers/gophers.go
@@ -12,6 +12,7 @@
"golang.org/x/build/gerrit"
)
+// Person represents a person.
type Person struct {
Name string // "Foo Bar"
Github string // "FooBar" (orig case, no '@')
@@ -63,10 +64,27 @@
// keys are "@lowercasegithub", "lowercase name", "lowercase@email.com".
var idToPerson = map[string]*Person{}
+// GetPerson looks up a person by id and returns one if found,
+// or nil otherwise.
+//
+// The id is case insensitive, and may be one of:
+//
+// • full name (for example, "Dmitri Shuralyov")
+//
+// • GitHub username (for example, "@dmitshur"), leading '@' is mandatory
+//
+// • Gerrit <account ID>@<instance ID> (for example, "6005@62eb7196-b449-3ce5-99f1-c037f21e1705")
+//
+// • email (for example, "dmitshur@golang.org")
+//
+// Only exact matches are supported.
+//
func GetPerson(id string) *Person {
return idToPerson[strings.ToLower(id)]
}
+// GetGerritPerson looks up a person from the Gerrit account ai.
+// It uses the name and email in the Gerrit account for the lookup.
func GetGerritPerson(ai gerrit.AccountInfo) *Person {
if p := GetPerson(ai.Name); p != nil {
return p
