docs: add docstrings for walker/visitor handlers/rules

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
 		}

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
 	}

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),

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),