From 642666fa59384a63835317ca301860a5ed490c53 Mon Sep 17 00:00:00 2001
From: James Houlahan <james.houlahan@protonmail.com>
Date: Tue, 18 Aug 2020 10:38:27 +0200
Subject: [PATCH] docs: add docstrings for walker/visitor handlers/rules

---
 pkg/message/parser/parser.go    | 7 +++++--
 pkg/message/parser/part_test.go | 4 ++--
 pkg/message/parser/visitor.go   | 3 +++
 pkg/message/parser/walker.go    | 8 ++++++++
 4 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/pkg/message/parser/parser.go b/pkg/message/parser/parser.go
index 41790cdd..3cb06f5f 100644
--- a/pkg/message/parser/parser.go
+++ b/pkg/message/parser/parser.go
@@ -60,10 +60,13 @@ func (p *Parser) Root() *Part {
 	return p.root
 }
 
-func (p *Parser) Part(number []int) (part *Part, err error) {
+// Section returns the message part referred to by the given section. A section
+// is zero or more integers. For example, section 1.2.3 will return the third
+// part of the second part of the first part of the message.
+func (p *Parser) Section(section []int) (part *Part, err error) {
 	part = p.root
 
-	for _, n := range number {
+	for _, n := range section {
 		if part, err = part.Child(n); err != nil {
 			return
 		}
diff --git a/pkg/message/parser/part_test.go b/pkg/message/parser/part_test.go
index 4d925b25..9818f3b9 100644
--- a/pkg/message/parser/part_test.go
+++ b/pkg/message/parser/part_test.go
@@ -46,7 +46,7 @@ func TestPart(t *testing.T) {
 	}
 
 	for partNumber, wantContType := range wantParts {
-		part, err := p.Part(getPartNumber(partNumber))
+		part, err := p.Section(getSectionNumber(partNumber))
 		require.NoError(t, err)
 
 		contType, _, err := part.Header.ContentType()
@@ -55,7 +55,7 @@ func TestPart(t *testing.T) {
 	}
 }
 
-func getPartNumber(s string) (part []int) {
+func getSectionNumber(s string) (part []int) {
 	if s == "" {
 		return
 	}
diff --git a/pkg/message/parser/visitor.go b/pkg/message/parser/visitor.go
index 537ecfd6..42a1b4d9 100644
--- a/pkg/message/parser/visitor.go
+++ b/pkg/message/parser/visitor.go
@@ -41,6 +41,9 @@ type visitorRule struct {
 	fn VisitorRule
 }
 
+// RegisterRule defines what to do when visiting a part whose content type
+// matches the given regular expression.
+// If a part matches multiple rules, the one registered first will be used.
 func (v *Visitor) RegisterRule(contentTypeRegex string, fn VisitorRule) *Visitor {
 	v.rules = append(v.rules, &visitorRule{
 		re: regexp.MustCompile(contentTypeRegex),
diff --git a/pkg/message/parser/walker.go b/pkg/message/parser/walker.go
index 7f2cfb75..d607079f 100644
--- a/pkg/message/parser/walker.go
+++ b/pkg/message/parser/walker.go
@@ -51,11 +51,16 @@ func (w *Walker) walkOverPart(p *Part) error {
 	return nil
 }
 
+// RegisterDefaultHandler registers a handler that will be called on every part
+// that doesn't match a registered content type/disposition handler.
 func (w *Walker) RegisterDefaultHandler(fn HandlerFunc) *Walker {
 	w.defaultHandler = fn
 	return w
 }
 
+// RegisterContentTypeHandler registers a handler that will be called when a
+// part's content type matches the given regular expression.
+// If a part matches multiple handlers, the one registered first will be chosen.
 func (w *Walker) RegisterContentTypeHandler(typeRegExp string, fn HandlerFunc) *Walker {
 	w.handlers = append(w.handlers, &handler{
 		typeRegExp: regexp.MustCompile(typeRegExp),
@@ -65,6 +70,9 @@ func (w *Walker) RegisterContentTypeHandler(typeRegExp string, fn HandlerFunc) *
 	return w
 }
 
+// RegisterContentDispositionHandler registers a handler that will be called
+// when a part's content disposition matches the given regular expression.
+// If a part matches multiple handlers, the one registered first will be chosen.
 func (w *Walker) RegisterContentDispositionHandler(dispRegExp string, fn HandlerFunc) *Walker {
 	w.handlers = append(w.handlers, &handler{
 		dispRegExp: regexp.MustCompile(dispRegExp),