@redpanda-data/docs-extensions-and-macros 5.14.0 → 5.22.0

package/macros/prop.js

@@ -7,6 +7,7 @@
  *   prop:cloud_storage_enabled[]
  *   prop:iceberg_enabled[link=true]
  *   prop:retention.ms[link=true,page=properties/topic-properties]
+ *   prop:cloud_storage_enabled[link=true,page=cloud:reference:properties/cluster-properties]
  *   prop:write_caching_default[text=write caching]
  *
  * The property renders as a marked <code> element that the docs UI decorates
@@ -54,11 +55,17 @@
  * a page in this component actually documents it. The page is discovered by
  * indexing which reference-module page documents each property, scanning
  * property headings in the partials each page includes and respecting include
- * tag filters such as tags=redpanda-cloud. Links are therefore
+ * tag filters such as tags=redpanda-cloud. Discovered links are therefore
  * component-relative and stay correct if properties are split across
- * different pages later. Nothing is ever linked across components, and no
- * page target is guessed from a property's scope: a link the build cannot
- * verify would be a broken link. Use page= to set the target explicitly.
+ * different pages later: nothing is ever discovered across components, and no
+ * page target is guessed from a property's scope, because a link the build
+ * cannot verify would be a broken link.
+ *
+ * Use page= to set the target explicitly instead of discovering it -- an
+ * override the build does not verify either way, so it may name any page that
+ * documents the property, in this component or another: a bare name
+ * (properties/topic-properties) stays module-relative within reference here,
+ * while module:page or component:module:page points anywhere else.
  *
  * With helm-path=auto, pages rendered with the env-kubernetes attribute
  * display the property as its Helm values path (storage.tiered.config.*
@@ -814,6 +821,23 @@ function reportUnpublishedProperty ({ name, registry, mode, filePath }) {
   ))
 }
 
+/**
+ * Resolve a page= value into the resource ID prefix an xref needs, before the
+ * trailing .adoc. A bare name (no colon) is module-relative within reference
+ * in the page's own component, matching every page= value published today.
+ * Qualifying it with a module (module:page) or a component and module
+ * (component:module:page) points the link anywhere else the property is
+ * documented: page= is never build-verified (buildPageIndex only runs when
+ * page= is absent), so restricting its shape bought no safety, only
+ * inflexibility.
+ *
+ * @param {string} page
+ * @returns {string}
+ */
+function resolvePageTarget (page) {
+  return page.includes(':') ? page : `reference:${page}`
+}
+
 /**
  * Build the AsciiDoc content emitted for one macro instance. Exported for
  * unit testing.
@@ -823,7 +847,10 @@ function reportUnpublishedProperty ({ name, registry, mode, filePath }) {
  * @param {string} [opts.text] - Display text override.
  * @param {boolean} [opts.link] - Whether to link to the reference page. Ignored
  *   without a page: the macro never guesses a target.
- * @param {string} [opts.page] - Reference page (module-relative, no .adoc).
+ * @param {string} [opts.page] - Reference page. A bare name (no colon) is
+ *   module-relative within reference in the current component; qualify it
+ *   with a module (module:page) or a component and module
+ *   (component:module:page) to point elsewhere. No .adoc.
  * @param {string} [opts.scope] - config_scope, used only for the Helm path.
  * @param {string} opts.role - CSS class for the code element.
  * @param {boolean} [opts.plain] - Render unmarked code (no tooltip, no link)
@@ -834,7 +861,7 @@ function buildPropContent ({ name, text, link, page, scope, role, helmPath = fal
   const display = text || (helmPath && helmValuesPath(name, scope)) || name
   if (plain) return `<code>${display}</code>`
   const inner = link && page
-    ? `xref:reference:${page}.adoc#${propertyAnchor(name)}[${display}]`
+    ? `xref:${resolvePageTarget(page)}.adoc#${propertyAnchor(name)}[${display}]`
     : display
   // Escape every interpolated attribute value. role comes from a site
   // attribute, docUrl from a page's published URL, and name from a dataset
@@ -980,6 +1007,7 @@ function register (registry, config = {}) {
 
 module.exports.register = register
 module.exports.buildPropContent = buildPropContent
+module.exports.resolvePageTarget = resolvePageTarget
 module.exports.propertyAnchor = propertyAnchor
 module.exports.helmValuesPath = helmValuesPath
 module.exports.loadPropertiesFor = loadPropertiesFor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.14.0",
+  "version": "5.22.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -32,6 +32,7 @@
     "test:python": "./__tests__/tools/property-extractor/setup-and-test.sh",
     "test:cgo": "node __tests__/tools/cgo-detection.test.js",
     "test:all": "npm run test && npm run test:python && npm run test:cgo",
+    "eval:doc-strings": "node evals/doc-strings/run-evals.js",
     "generate:cli-docs": "node tools/generate-cli-docs.js",
     "bundle:admin": "doc-tools generate bundle-openapi --surface admin",
     "bundle:connect": "doc-tools generate bundle-openapi --surface connect",

package/tools/generate-cli-docs.js

@@ -277,74 +277,35 @@ IMPORTANT: This documentation is auto-generated. Do not edit manually. Run \`npm
   const mainData = parseHelp(mainHelp);
   doc += generateCommandDoc('', mainData, null, 2);
 
-  // Top-level commands (excluding 'generate' which has subcommands)
-  const topLevelCommands = [
-    'install-test-dependencies',
-    'get-redpanda-version',
-    'get-console-version',
-    'link-readme',
-    'fetch',
-    'setup-mcp',
-    'validate-mcp',
-    'preview-prompt',
-    'mcp-version'
-  ];
-
-  topLevelCommands.forEach(cmd => {
-    console.log(`  Generating docs for: ${cmd}`);
-    const help = getHelpOutput(cmd);
-    const data = parseHelp(help);
-    const jsdoc = jsdocs[cmd];
-    doc += generateCommandDoc(cmd, data, jsdoc, 2);
-  });
-
-  // Generate command and its subcommands
-  console.log('  Generating docs for: generate');
-  const generateHelp = getHelpOutput('generate');
-  const generateData = parseHelp(generateHelp);
-  doc += generateCommandDoc('generate', generateData, null, 2);
-
-  // Generate subcommands
-  const generateSubcommands = [
-    'property-docs',
-    'metrics-docs',
-    'rpk-docs',
-    'rpk-env-partial',
-    'rpcn-connector-docs',
-    'helm-spec',
-    'cloud-regions',
-    'crd-spec',
-    'bundle-openapi',
-    'update-connect-version',
-    'migrate-rpcn-metadata',
-    'migrate-rpcn-descriptions'
-  ];
-
-  generateSubcommands.forEach(subcmd => {
-    console.log(`    Generating docs for: generate ${subcmd}`);
-    const help = getHelpOutput(`generate ${subcmd}`);
-    const data = parseHelp(help);
-    const jsdoc = jsdocs[subcmd];
-    doc += generateCommandDoc(`generate ${subcmd}`, data, jsdoc, 3);
-  });
+  // Walk the command tree the CLI itself reports, rather than three
+  // hardcoded lists. Those lists had drifted both ways at once: lint-strings,
+  // preview-string and overrides were undocumented while README.adoc points
+  // users here as the complete reference, and `preview-prompt` was still
+  // getting a section even though the command no longer exists (the generator
+  // fell back to the top-level help for it, so the section was real-looking
+  // and wrong). A command group is anything whose help lists Commands: of its
+  // own, so a new command or subcommand is documented the moment it is
+  // registered.
+  const documentCommand = (commandPath, level) => {
+    const label = commandPath.join(' ');
+    console.log(`${'  '.repeat(level - 1)}Generating docs for: ${label}`);
+    const data = parseHelp(getHelpOutput(label));
+    const jsdoc = jsdocs[commandPath[commandPath.length - 1]];
+    doc += generateCommandDoc(label, data, jsdoc, level);
+    for (const child of data.commands) {
+      // Commander lists `help [command]` in every group; it is not a command
+      // anyone documents.
+      const childName = child.name.split(/[\s[<]/)[0];
+      if (childName === 'help') continue;
+      documentCommand([...commandPath, childName], level + 1);
+    }
+  };
 
-  // Validate command and its subcommands
-  console.log('  Generating docs for: validate');
-  const validateHelp = getHelpOutput('validate');
-  const validateData = parseHelp(validateHelp);
-  doc += generateCommandDoc('validate', validateData, null, 2);
-
-  const validateSubcommands = [
-    'enterprise-features'
-  ];
-
-  validateSubcommands.forEach(subcmd => {
-    console.log(`    Generating docs for: validate ${subcmd}`);
-    const help = getHelpOutput(`validate ${subcmd}`);
-    const data = parseHelp(help);
-    const jsdoc = jsdocs[subcmd];
-    doc += generateCommandDoc(`validate ${subcmd}`, data, jsdoc, 3);
-  });
+  for (const child of mainData.commands) {
+    const childName = child.name.split(/[\s[<]/)[0];
+    if (childName === 'help') continue;
+    documentCommand([childName], 2);
+  }
 
   // Write to file
   const outputPath = path.join(__dirname, '..', 'CLI_REFERENCE.adoc');

package/tools/lint-strings/diff.js

@@ -0,0 +1,137 @@
+'use strict'
+
+const { spawnSync } = require('child_process')
+
+/**
+ * Diff support for declaration-anchored linting.
+ *
+ * Diff mode never lints hunks directly: descriptions are clang-format-wrapped
+ * adjacent string literals, so a PR touching one wrapped line must surface the
+ * FULL declaration. The flow is: parse `git diff <base>...HEAD` into changed
+ * (post-image) line numbers per file, route each file to a surface by path,
+ * extract declarations from those files at HEAD, and keep declarations whose
+ * line span intersects the changed lines.
+ */
+
+/**
+ * Path -> surface routing table. First match wins. A surface routed here
+ * without an extractor in the index.js SURFACES registry is reported as
+ * not-yet-supported instead of silently dropping the files.
+ */
+const SURFACE_ROUTES = [
+  { surface: 'properties', pattern: /^src\/v\/config\// },
+  { surface: 'metrics', pattern: /(^|\/)[^/]*probe\.cc$|^src\/v\/metrics\// },
+  { surface: 'rpk', pattern: /^src\/go\/rpk\/pkg\/cli\// },
+  // Both chart layouts ship: charts/<name>/chart/values.yaml (redpanda,
+  // console) and charts/<name>/values.yaml (connectors).
+  { surface: 'helm', pattern: /^charts\/[^/]+\/(chart\/)?values\.yaml$/ },
+  { surface: 'crd', pattern: /^operator\/api\// },
+  { surface: 'connect', pattern: /^internal\/impl\// }
+]
+
+/**
+ * Route a repo-relative file path to a surface id, or null when the file is
+ * not a doc-string surface.
+ */
+function routeFile (file) {
+  for (const route of SURFACE_ROUTES) {
+    if (route.pattern.test(file)) return route.surface
+  }
+  return null
+}
+
+/**
+ * Run `git diff <base>...HEAD` in the repo and parse it into a map of
+ * file -> Set of changed line numbers in the post-image (HEAD) version.
+ * Deleted files (no post-image) are omitted.
+ *
+ * @param {string} repo - Path to the git checkout
+ * @param {string} base - Base ref (`git diff base...HEAD`)
+ * @returns {Map<string, Set<number>>}
+ */
+function getChangedLines (repo, base) {
+  const result = spawnSync(
+    'git',
+    ['diff', '--unified=0', '--no-color', `${base}...HEAD`],
+    { cwd: repo, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 }
+  )
+  if (result.error) throw result.error
+  if (result.status !== 0) {
+    throw new Error(`git diff ${base}...HEAD failed in ${repo}: ${result.stderr || result.stdout}`)
+  }
+  return parseUnifiedDiff(result.stdout)
+}
+
+/**
+ * Parse unified diff text (produced with --unified=0) into
+ * file -> Set(changed post-image line numbers).
+ */
+function parseUnifiedDiff (diffText) {
+  const changed = new Map()
+  let currentFile = null
+
+  for (const line of diffText.split('\n')) {
+    // Only git's file headers count: "+++ b/<path>" or "+++ /dev/null".
+    // (An added content line that itself starts with "++ " would otherwise
+    // look like a header under --unified=0.)
+    if (line.startsWith('+++ b/')) {
+      currentFile = line.slice(6).trim()
+      continue
+    }
+    if (line.startsWith('+++ /dev/null')) {
+      currentFile = null
+      continue
+    }
+    if (!line.startsWith('@@') || currentFile === null) continue
+
+    const hunk = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/)
+    if (!hunk) continue
+    const start = parseInt(hunk[1], 10)
+    const count = hunk[2] === undefined ? 1 : parseInt(hunk[2], 10)
+    if (count === 0) continue // pure deletion: no post-image lines
+
+    if (!changed.has(currentFile)) changed.set(currentFile, new Set())
+    const lines = changed.get(currentFile)
+    for (let i = 0; i < count; i++) lines.add(start + i)
+  }
+
+  return changed
+}
+
+/**
+ * Group changed files by surface.
+ *
+ * @param {Map<string, Set<number>>} changedLines - From getChangedLines
+ * @returns {Object} surface -> Map(file -> Set(lines))
+ */
+function classifyDiff (changedLines) {
+  const bySurface = {}
+  for (const [file, lines] of changedLines) {
+    const surface = routeFile(file)
+    if (!surface) continue
+    if (!bySurface[surface]) bySurface[surface] = new Map()
+    bySurface[surface].set(file, lines)
+  }
+  return bySurface
+}
+
+/**
+ * True when the inclusive line span [lineStart, lineEnd] contains at least
+ * one changed line.
+ */
+function spanIntersects (lineStart, lineEnd, lineSet) {
+  if (lineStart == null || lineEnd == null || !lineSet) return false
+  for (const line of lineSet) {
+    if (line >= lineStart && line <= lineEnd) return true
+  }
+  return false
+}
+
+module.exports = {
+  SURFACE_ROUTES,
+  routeFile,
+  getChangedLines,
+  parseUnifiedDiff,
+  classifyDiff,
+  spanIntersects
+}

package/tools/lint-strings/engine.js

@@ -0,0 +1,163 @@
+'use strict'
+
+/**
+ * Rule runner for lint-strings.
+ *
+ * Adopts the VALIDATION_RULES shape from tools/rpk-docs/validate-output.js:
+ * each rule is { name, description, severity, check() -> issues[] }, with
+ * skipRules/onlyRules filtering and a byRule summary. The difference is the
+ * unit of work: rules here check one extracted *declaration* (a property,
+ * metric, rpk command, ...) rather than a generated .adoc file.
+ *
+ * Declaration shape (produced by the surface modules in ./surfaces):
+ *   {
+ *     surface: 'properties',          // surface id
+ *     name: 'cluster_id',             // declared name (null if unresolvable)
+ *     file: 'src/v/config/...',       // path relative to --repo
+ *     line_start: 1852,               // 1-indexed, inclusive
+ *     line_end: 1857,                 //   spans the FULL declaration
+ *     string: 'The doc string',       // extracted doc string (null if none)
+ *     declaration_text: '...',        // exact source lines of the span
+ *     convention: { ... },            // surface conventions (echoed in findings)
+ *     meta: { ... }                   // surface-specific extras for rules
+ *   }
+ *
+ * Severity levels: error | warning | info.
+ */
+
+const SEVERITIES = ['error', 'warning', 'info']
+
+/**
+ * Run rules over a list of declarations.
+ *
+ * @param {Array} declarations - Declarations from a surface module
+ * @param {Array} rules - Rules ({ name, severity, check(decl) -> issues[] }).
+ *   Optional rule fields:
+ *   - runOnUnverifiable: also run when decl.meta.unverifiable is set
+ *     (all other rules are skipped for unverifiable declarations, so a
+ *     non-literal source string can never produce an error)
+ * @param {Object} options - { skipRules: [names], onlyRules: [names] }
+ * @returns {Object} { findings, summary: { byRule, bySurface } }
+ */
+function runRules (declarations, rules, options = {}) {
+  const { skipRules = [], onlyRules = null } = options
+  const findings = []
+  const summary = emptySummary()
+
+  for (const decl of declarations) {
+    summary.totalDeclarations++
+    ensureSurface(summary, decl.surface).declarations++
+    const issues = []
+
+    for (const rule of rules) {
+      if (skipRules.includes(rule.name)) continue
+      if (onlyRules && !onlyRules.includes(rule.name)) continue
+      // Unverifiable declarations (for example, a metric description built
+      // with fmt::format) only run rules that opt in; they must never error.
+      if (decl.meta && decl.meta.unverifiable && !rule.runOnUnverifiable) continue
+
+      try {
+        for (const issue of rule.check(decl) || []) {
+          const severity = issue.severity || rule.severity
+          issues.push({
+            id: rule.name,
+            severity: SEVERITIES.includes(severity) ? severity : 'warning',
+            message: issue.message
+          })
+        }
+      } catch (err) {
+        issues.push({
+          id: rule.name,
+          severity: 'error',
+          message: `Rule execution failed: ${err.message}`
+        })
+      }
+    }
+
+    if (issues.length === 0) continue
+
+    findings.push({
+      surface: decl.surface,
+      name: decl.name,
+      file: decl.file,
+      line_start: decl.line_start,
+      line_end: decl.line_end,
+      string: decl.string,
+      declaration_text: decl.declaration_text,
+      rules: issues,
+      convention: decl.convention || {},
+      in_pr_diff: Boolean(decl.in_pr_diff)
+    })
+
+    tally(summary, decl.surface, issues)
+  }
+
+  return { findings, summary }
+}
+
+function emptySummary () {
+  return {
+    totalDeclarations: 0,
+    flaggedDeclarations: 0,
+    errors: 0,
+    warnings: 0,
+    info: 0,
+    byRule: {},
+    bySurface: {}
+  }
+}
+
+function ensureSurface (summary, surface) {
+  if (!summary.bySurface[surface]) {
+    summary.bySurface[surface] = { declarations: 0, flagged: 0, errors: 0, warnings: 0, info: 0 }
+  }
+  return summary.bySurface[surface]
+}
+
+function tally (summary, surface, issues) {
+  summary.flaggedDeclarations++
+  ensureSurface(summary, surface).flagged++
+
+  for (const issue of issues) {
+    if (!summary.byRule[issue.id]) {
+      summary.byRule[issue.id] = { errors: 0, warnings: 0, info: 0 }
+    }
+    const bucket = issue.severity === 'error' ? 'errors' : issue.severity === 'warning' ? 'warnings' : 'info'
+    summary.byRule[issue.id][bucket]++
+    summary.bySurface[surface][bucket]++
+    summary[bucket]++
+  }
+}
+
+/**
+ * Merge per-surface run results into one combined result.
+ */
+function mergeResults (results) {
+  const merged = { findings: [], summary: emptySummary() }
+  for (const result of results) {
+    merged.findings.push(...result.findings)
+    const s = result.summary
+    merged.summary.totalDeclarations += s.totalDeclarations
+    merged.summary.flaggedDeclarations += s.flaggedDeclarations
+    merged.summary.errors += s.errors
+    merged.summary.warnings += s.warnings
+    merged.summary.info += s.info
+    for (const [rule, counts] of Object.entries(s.byRule)) {
+      if (!merged.summary.byRule[rule]) merged.summary.byRule[rule] = { errors: 0, warnings: 0, info: 0 }
+      merged.summary.byRule[rule].errors += counts.errors
+      merged.summary.byRule[rule].warnings += counts.warnings
+      merged.summary.byRule[rule].info += counts.info
+    }
+    for (const [surface, counts] of Object.entries(s.bySurface)) {
+      if (!merged.summary.bySurface[surface]) {
+        merged.summary.bySurface[surface] = { declarations: 0, flagged: 0, errors: 0, warnings: 0, info: 0 }
+      }
+      for (const key of Object.keys(counts)) {
+        merged.summary.bySurface[surface][key] += counts[key]
+      }
+    }
+  }
+  return merged
+}
+
+module.exports = { runRules, mergeResults, SEVERITIES }

package/tools/lint-strings/fixtures/connect/lint_connect.go

@@ -0,0 +1,67 @@
+// Package lintfixture is a lint-strings test fixture mirroring connect
+// ConfigSpec shapes. It only needs to parse as Go text for the scanner.
+package lintfixture
+
+import (
+	"github.com/redpanda-data/benthos/v4/public/service"
+)
+
+const (
+	// Field name constants resolve like the kfc* pattern in franz_client.go.
+	fixFieldSeedBrokers = "seed_brokers"
+	fixFieldClientID    = "client_id"
+
+	fixFieldSeedBrokersDescription = "A list of broker addresses to connect to in order to establish the connection."
+)
+
+func fixtureInputConfig() *service.ConfigSpec {
+	return service.NewConfigSpec().
+		Categories("Services").
+		Summary(`A fixture input using the https://example.com[example client library^].`).
+		Description(`
+When a consumer group is specified this input consumes one or more topics.
+
+This fixture exercises the ` + "`raw` + interpreted + `raw`" + ` concatenation idiom.
+
+== Metadata
+
+This heading and the table below are legitimate AsciiDoc:
+
+|===
+| kafka_key | The record key
+|===
+`).
+		Fields(fixtureConfigFields()...)
+}
+
+func fixtureConfigFields() []*service.ConfigField {
+	return []*service.ConfigField{
+		service.NewStringListField(fixFieldSeedBrokers).
+			Description(fixFieldSeedBrokersDescription + " When omitted the global block is referenced.").
+			Example([]string{"localhost:9092"}),
+		service.NewStringField(fixFieldClientID).
+			Description("An identifier for the client connection.").
+			Default("fixture").
+			Advanced(),
+		// Composite helper with built-in docs: never flagged.
+		service.NewTLSToggledField("tls"),
+		// Known-bad: a bare constructor with no Description ships blank.
+		service.NewStringField("naked_field").
+			Default(""),
+		// Known-bad: description merely restates the field name.
+		service.NewDurationField("poll_interval").
+			Description("Poll interval."),
+		// Deprecated fields are exempt from the missing-description rule.
+		service.NewStringField("old_token").Deprecated().Default(""),
+		// Dynamic description: skipped silently, never guessed at.
+		service.NewStringField("dynamic_field").
+			Description(dynamicDescription()),
+	}
+}
+
+func init() {
+	service.MustRegisterBatchInput("fixture_input", fixtureInputConfig(),
+		func(conf *service.ParsedConfig, mgr *service.Resources) (service.BatchInput, error) {
+			return nil, nil
+		})
+}

package/tools/lint-strings/fixtures/crd/crd-ref-docs-config.yaml

@@ -0,0 +1,15 @@
+# lint-strings test fixture mirroring operator/crd-ref-docs-config.yaml.
+processor:
+  ignoreTypes:
+  - 'List$'
+  - 'Deprecated.*$'
+  ignoreFields:
+  - 'migration$'
+  customMarkers:
+  - name: "hidefromdoc"
+    target: field
+  - name: "hidefromdoc"
+    target: type
+
+render:
+  kubernetesVersion: 1.28

package/tools/lint-strings/fixtures/crd/lint_types.go

@@ -0,0 +1,57 @@
+// Package v1alpha2 is a lint-strings test fixture mirroring the operator
+// API type shapes. It only needs to parse as Go text for the scanner.
+package v1alpha2
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// WidgetSpec defines the configuration of a fixture widget.
+type WidgetSpec struct {
+	// ClusterSource is a reference to the cluster hosting the widget.
+	// It leads with the Go field name, which users never type.
+	// +required
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="ClusterSource is immutable"
+	ClusterSource *ClusterSource `json:"cluster"`
+	// Text is the actual unescaped text of a widget. The Go name matches
+	// the json name (case only), so this conforms.
+	// +required
+	Text string `json:"text,omitempty"`
+	// Specifies how many replicas to run. Conforming: describes behavior,
+	// never names the field.
+	// +kubebuilder:default=3
+	Replicas *int `json:"replicas,omitempty"`
+	// +hidefromdoc
+	// Internal knob hidden from the docs; never linted.
+	HiddenKnob string `json:"hiddenKnob,omitempty"`
+	NotSerialized string `json:"-"`
+}
+
+// WidgetReference is a way for one widget to reference another. Its fields
+// are undocumented on purpose (the known-bad this fixture exists for).
+type WidgetReference struct {
+	Name    string `json:"name"`
+	Subject string `json:"subject"`
+	Version int    `json:"version"`
+}
+
+// WidgetList is ignored via the config's ignoreTypes ('List$').
+type WidgetList struct {
+	metav1.TypeMeta `json:",inline"`
+	UndocumentedButIgnored string `json:"items"`
+}
+
+// DeprecatedWidget matches ignoreTypes ('Deprecated.*$').
+type DeprecatedWidget struct {
+	Old string `json:"old"`
+}
+
+// +hidefromdoc
+// HiddenStruct is hidden from the docs wholesale.
+type HiddenStruct struct {
+	Anything string `json:"anything"`
+}
+
+func (w *WidgetSpec) helper() bool { // functions between types must not confuse the parser
+	return w != nil && len(w.Text) > 0
+}