improve comments

Author: MarkRosemaker

path_item.go

@@ -93,6 +93,7 @@ func (p *PathItem) Operations(yield func(string, *Operation) bool) {
 }
 
 // SetOperation sets the operation for the given method.
+// The method is case-insensitive.
 func (p *PathItem) SetOperation(method string, op *Operation) {
 	switch strings.ToUpper(method) {
 	case http.MethodGet:

path_items.go

@@ -11,6 +11,7 @@ import (
 
 type PathItems map[string]*PathItemRef
 
+// Validate checks that all keys and values are valid.
 func (ps PathItems) Validate() error {
 	for name, p := range ps.ByIndex() {
 		if err := validateKey(name); err != nil {

path_parsed.go

@@ -15,6 +15,7 @@ type ParsedPath struct {
 	VariableNames []string
 }
 
+// Parse parses the path, returning a ParsedPath which includes a format specifier (see [fmt]) and a list of all variable names in order.
 func (path Path) Parse() ParsedPath {
 	p := ParsedPath{}
 

ref.go

@@ -43,7 +43,7 @@ type referencable[T any] interface {
 	*T
 }
 
-// refOrValue is a reference to a component.
+// refOrValue is a reference to a component or the component itself.
 type refOrValue[T any, O referencable[T]] struct {
 	// The referenced object.
 	Value O `json:",inline" yaml:",inline"`