|
5 | 5 | // Go doc comment is carried into a Swagger title / description (the |
6 | 6 | // Options.CleanGoDoc feature). |
7 | 7 | // |
8 | | -// Phase 1 (this package as it stands) covers the resolution-free transforms: |
| 8 | +// Two transforms apply to godoc-derived prose: |
9 | 9 | // |
10 | | -// - reference-style link definition lines (`[text]: url`) are dropped; |
11 | | -// - godoc doc-link spans (`[Widget]`, `[pkg.Type]`, `[Order.Field]`) have |
12 | | -// their brackets removed and the (leaf) identifier humanized via the swag |
13 | | -// name mangler — e.g. `[CustName]` → "cust name"; |
14 | | -// - the first identifier of the prose is restored to sentence case. |
| 10 | +// - resolution-free cleanup: reference-style link definition lines |
| 11 | +// (`[text]: url`) are dropped; godoc doc-link spans (`[Widget]`, |
| 12 | +// `[pkg.Type]`, `[Order.Field]`) have their brackets removed and the (leaf) |
| 13 | +// identifier humanized via the swag name mangler — e.g. `[CustName]` → |
| 14 | +// "cust name"; the first identifier of the prose is restored to sentence |
| 15 | +// case; |
| 16 | +// - idiom recomposition: when a [Resolver] maps a doc-link (or the leading |
| 17 | +// godoc-convention self-name) to an emitted schema, the span is replaced by |
| 18 | +// a [marker] carrying that schema's fully-qualified definition key. Markers |
| 19 | +// are resolved to the schema's final exposed name by [SubstituteMarkers], |
| 20 | +// run after the spec builder has reduced definition names. This two-step |
| 21 | +// dance is needed because the final name is only known at the very end of |
| 22 | +// the build, whereas which prose is godoc-derived is only known here, at the |
| 23 | +// consumption seam. |
15 | 24 | // |
16 | | -// A later phase adds identifier→schema resolution so a doc-link that points at |
17 | | -// an emitted definition is recomposed to that definition's exposed name rather |
18 | | -// than merely humanized. The recognizer regexes are adapted from the |
| 25 | +// With a nil [Options.Resolver] (and nil Self), only the resolution-free cleanup |
| 26 | +// runs and no marker is produced. The recognizer regexes are adapted from the |
19 | 27 | // battle-tested github.com/fredbi/go-fred-mcp/pkg/doc-filters/godoc-filter; the |
20 | 28 | // key difference is that this package *rewrites* the prose whereas that tool |
21 | 29 | // *redacts* (length-preserving blanking) for masking. |
@@ -48,17 +56,57 @@ var refDefLineRE = regexp.MustCompile(`^[ \t]*\[[^\]]+\]:[ \t]+\S.*$`) |
48 | 56 | // interior reference-definition line) back to a single paragraph break. |
49 | 57 | var multiNewlineRE = regexp.MustCompile(`\n{3,}`) |
50 | 58 |
|
51 | | -// Clean applies the resolution-free godoc filtering to text using m for |
52 | | -// identifier humanization. It is the caller's responsibility to apply Clean |
53 | | -// ONLY to godoc-derived prose — never to author-written swagger:title / |
54 | | -// swagger:description override text. Clean never mutates m. |
55 | | -func Clean(text string, m *mangling.NameMangler) string { |
| 59 | +// identRE matches a leading Go-identifier chain (the godoc-convention self-name |
| 60 | +// at the start of a doc comment, e.g. "Widget" in "Widget does things"). |
| 61 | +var identRE = regexp.MustCompile(`^[\p{L}_][\p{L}\p{N}_]*`) |
| 62 | + |
| 63 | +// Resolution is the outcome of resolving a doc-link reference to an emitted |
| 64 | +// schema. DefKey is the referenced type's fully-qualified definition key (whose |
| 65 | +// final exposed name is substituted later); Suffix is the already-exposed field |
| 66 | +// chain for a dotted member reference (e.g. ".customer_name"), or "" for a bare |
| 67 | +// type reference. |
| 68 | +type Resolution struct { |
| 69 | + DefKey string |
| 70 | + Suffix string |
| 71 | +} |
| 72 | + |
| 73 | +// Resolver maps a doc-link reference — the bracket content with any leading `*` |
| 74 | +// stripped, e.g. "Order.CustName" or "pkg.Type" — to a [Resolution]. It returns |
| 75 | +// ok=false when the reference does not resolve to an emitted schema, in which |
| 76 | +// case the caller humanizes the leaf identifier instead. |
| 77 | +type Resolver func(ref string) (Resolution, bool) |
| 78 | + |
| 79 | +// SelfRef describes the declaration whose godoc is being cleaned, so the leading |
| 80 | +// godoc-convention self-name ("Widget" in "Widget does things") can be |
| 81 | +// recomposed to the declaration's own exposed name. Name is the Go identifier; |
| 82 | +// DefKey is its fully-qualified definition key. |
| 83 | +type SelfRef struct { |
| 84 | + Name string |
| 85 | + DefKey string |
| 86 | +} |
| 87 | + |
| 88 | +// Options configures Clean. |
| 89 | +type Options struct { |
| 90 | + // Mangler humanizes leaf identifiers (and marker fallbacks). Required. |
| 91 | + Mangler *mangling.NameMangler |
| 92 | + // Resolver, when non-nil, recomposes resolvable doc-links into markers; |
| 93 | + // nil selects resolution-free cleanup only. |
| 94 | + Resolver Resolver |
| 95 | + // Self, when non-nil, enables leading self-name recomposition. It has effect |
| 96 | + // only together with a non-nil Resolver. |
| 97 | + Self *SelfRef |
| 98 | +} |
| 99 | + |
| 100 | +// Clean applies godoc filtering to text. It is the caller's responsibility to |
| 101 | +// apply Clean ONLY to godoc-derived prose — never to author-written |
| 102 | +// swagger:title / swagger:description override text. Clean never mutates o. |
| 103 | +func Clean(text string, o Options) string { |
56 | 104 | if text == "" { |
57 | 105 | return text |
58 | 106 | } |
59 | 107 |
|
60 | 108 | text = dropRefDefLines(text) |
61 | | - text = rewriteDocLinks(text, m) |
| 109 | + text = rewrite(text, o) |
62 | 110 |
|
63 | 111 | return text |
64 | 112 | } |
@@ -92,44 +140,107 @@ func dropRefDefLines(text string) string { |
92 | 140 | return strings.TrimRight(out, " \t\n") |
93 | 141 | } |
94 | 142 |
|
95 | | -// rewriteDocLinks strips the brackets off each doc-link span and humanizes the |
96 | | -// leaf identifier; a span at the start of the prose is sentence-cased. |
97 | | -func rewriteDocLinks(text string, m *mangling.NameMangler) string { |
98 | | - locs := docLinkRE.FindAllStringIndex(text, -1) |
99 | | - if locs == nil { |
| 143 | +// span is one stretch of text to replace: a doc-link bracket span or the |
| 144 | +// leading self-name. |
| 145 | +type span struct { |
| 146 | + lo, hi int |
| 147 | + ref string // resolver reference (full inner chain, `*` stripped); self-name = Self.Name |
| 148 | + leaf string // trailing identifier, for the humanize fallback |
| 149 | + self bool |
| 150 | +} |
| 151 | + |
| 152 | +// rewrite replaces every doc-link span (and, when enabled, the leading |
| 153 | +// self-name) left to right, emitting a marker for resolvable references and the |
| 154 | +// humanized leaf otherwise. |
| 155 | +func rewrite(text string, o Options) string { |
| 156 | + spans := collectSpans(text, o) |
| 157 | + if len(spans) == 0 { |
100 | 158 | return text |
101 | 159 | } |
102 | 160 |
|
103 | 161 | var b strings.Builder |
104 | 162 | b.Grow(len(text)) |
105 | 163 | last := 0 |
106 | | - for _, loc := range locs { |
107 | | - b.WriteString(text[last:loc[0]]) |
108 | | - |
109 | | - span := text[loc[0]:loc[1]] |
110 | | - human := m.ToHumanNameLower(leafIdent(span)) |
111 | | - if isSentenceStart(text, loc[0]) { |
112 | | - human = capitalizeFirst(human) |
| 164 | + for _, s := range spans { |
| 165 | + if s.lo < last { |
| 166 | + continue // overlap guard (defensive; spans are non-overlapping) |
113 | 167 | } |
114 | | - b.WriteString(human) |
115 | | - |
116 | | - last = loc[1] |
| 168 | + b.WriteString(text[last:s.lo]) |
| 169 | + b.WriteString(replacement(s, text, o)) |
| 170 | + last = s.hi |
117 | 171 | } |
118 | 172 | b.WriteString(text[last:]) |
119 | 173 |
|
120 | 174 | return b.String() |
121 | 175 | } |
122 | 176 |
|
123 | | -// leafIdent extracts the trailing identifier of a doc-link span: it strips the |
124 | | -// surrounding brackets and an optional leading `*`, then keeps the last |
125 | | -// dot-separated segment (`[*inventory.Ledger]` → "Ledger"). |
126 | | -func leafIdent(span string) string { |
127 | | - inner := strings.TrimPrefix(span[1:len(span)-1], "*") |
128 | | - if i := strings.LastIndex(inner, "."); i >= 0 { |
129 | | - return inner[i+1:] |
| 177 | +// collectSpans gathers the leading self-name (when it matches Self.Name) and |
| 178 | +// every doc-link bracket span, in ascending position order. |
| 179 | +func collectSpans(text string, o Options) []span { |
| 180 | + var spans []span |
| 181 | + |
| 182 | + if o.Self != nil && o.Self.Name != "" { |
| 183 | + if loc := identRE.FindStringIndex(strings.TrimLeft(text, " \t")); loc != nil { |
| 184 | + offset := len(text) - len(strings.TrimLeft(text, " \t")) |
| 185 | + lo, hi := offset+loc[0], offset+loc[1] |
| 186 | + if text[lo:hi] == o.Self.Name { |
| 187 | + spans = append(spans, span{lo: lo, hi: hi, ref: o.Self.Name, leaf: o.Self.Name, self: true}) |
| 188 | + } |
| 189 | + } |
| 190 | + } |
| 191 | + |
| 192 | + for _, loc := range docLinkRE.FindAllStringIndex(text, -1) { |
| 193 | + inner := strings.TrimPrefix(text[loc[0]+1:loc[1]-1], "*") |
| 194 | + spans = append(spans, span{lo: loc[0], hi: loc[1], ref: inner, leaf: leafOf(inner)}) |
| 195 | + } |
| 196 | + |
| 197 | + return spans |
| 198 | +} |
| 199 | + |
| 200 | +// replacement computes the substitution text for one span: a marker when the |
| 201 | +// reference resolves to a schema, otherwise the humanized leaf (sentence-cased |
| 202 | +// at the start of the prose). A self-name without a Resolver is left verbatim |
| 203 | +// (its exposed name is unknowable without resolution). |
| 204 | +func replacement(s span, text string, o Options) string { |
| 205 | + titleize := isSentenceStart(text, s.lo) |
| 206 | + fallback := o.humanize(s.leaf) |
| 207 | + |
| 208 | + if o.Resolver != nil { |
| 209 | + if s.self { |
| 210 | + return encodeMarker(o.Self.DefKey, "", fallback, titleize) |
| 211 | + } |
| 212 | + if res, ok := o.Resolver(s.ref); ok { |
| 213 | + return encodeMarker(res.DefKey, res.Suffix, fallback, titleize) |
| 214 | + } |
| 215 | + } else if s.self { |
| 216 | + return text[s.lo:s.hi] |
| 217 | + } |
| 218 | + |
| 219 | + if titleize { |
| 220 | + return capitalizeFirst(fallback) |
| 221 | + } |
| 222 | + |
| 223 | + return fallback |
| 224 | +} |
| 225 | + |
| 226 | +// humanize renders an identifier as lower-case words; a nil mangler is treated |
| 227 | +// as the identity (defensive — callers always supply one). |
| 228 | +func (o Options) humanize(ident string) string { |
| 229 | + if o.Mangler == nil { |
| 230 | + return ident |
| 231 | + } |
| 232 | + |
| 233 | + return o.Mangler.ToHumanNameLower(ident) |
| 234 | +} |
| 235 | + |
| 236 | +// leafOf returns the trailing dot-separated segment of a reference chain |
| 237 | +// (`inventory.Ledger` → "Ledger"). |
| 238 | +func leafOf(ref string) string { |
| 239 | + if i := strings.LastIndex(ref, "."); i >= 0 { |
| 240 | + return ref[i+1:] |
130 | 241 | } |
131 | 242 |
|
132 | | - return inner |
| 243 | + return ref |
133 | 244 | } |
134 | 245 |
|
135 | 246 | // isSentenceStart reports whether pos is the first non-space byte of text — the |
|
0 commit comments