optimize-interceptor-docs

Optimize Interceptor Documentation

Membrane's reference pages (https://www.membrane-api.io/docs/) are generated from the Java source, not hand-written. The element name, attribute table, child cardinalities and "required" flags are derived from the @MCElement / @MCAttribute / @MCChildElement annotations and the JSON schema. The prose and the example come from Javadoc tags. So "writing docs" here means rewriting Javadoc — and getting it right depends on knowing exactly what the renderer consumes and what it rejects.

Goal: a page that reads like a precise reference entry — a one-glance summary, exact behaviour, one runnable YAML example, and a compact syntax sketch. Short but complete. No XML examples.

Workflow

1. Read the class and pull facts from code — never invent. Identify:
   • @MCElement(name=...) → the element name used in YAML.
   • every @MCAttribute setter → an attribute (default from the field initializer or @default; type from the setter param; enum values from the enum type).
   • every @MCChildElement setter → a child element / list (cardinality from List<…> vs single, order from order=).
   • handleRequest / init → real behaviour worth documenting: status codes, side effects (what it adds to the Exchange), what happens on the failure path, defaults applied when config is omitted.
   • which flows it actually acts in — check getAppliedFlow() and which of handleRequest/handleResponse/handleAbort are really overridden (and any flow.isRequest() guards inside them). An element can be wired for a flow but no-op there; document what runs, not what's declared. Only mention flow in the prose when it's special — i.e. the element acts in only the request flow or only the response flow. Acting in both request and response is the normal case; don't state it.
   • Don't trust the existing Javadoc — it's often copy-pasted from a sibling element and wrong. Verify every @default against the field initializer and every @description against the code (e.g. <for> shipped @default groovy for a field initialized to SpEL, and an in description that talked about a "test condition" lifted from <if>). Fix what the code contradicts.
2. Rewrite the class-level Javadoc: @topic, @description, @yaml. Keep the existing @topic unless it's clearly wrong.
   • @topic belongs on top-level elements — those that can appear directly in a flow: or at the api: level. Elements that are only ever used inside another interceptor or api as a child/sub-config (e.g. an extractor, a key store entry, a sub-element with component = false) do not get @topic.
3. Rewrite each attribute and child setter's Javadoc: @description, plus @default / @example for attributes.
4. Replace every XML sample with YAML, and add a [] | syntax sketch where the shape is non-trivial.
5. Validate — every tag value is parsed as XML by the build (see below). Confirm well-formedness; optionally compile to let the annotation processor check it.