add generator to extract javadoc in separate yaml

[christiangoerdes]

Summary by CodeRabbit

• New Features

  • YAML documentation generation is now automatically integrated into the annotation processing pipeline, producing structured docs per namespace describing elements, attributes and relationships.

• Improvements

  • Documentation output is now deterministically ordered via priority-based sorting to ensure consistent, predictable organization of generated docs.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a YAML documentation generator and integrates it into the annotation processor; adjusts doc entry sorting to use a priority-based order and related empty-value handling.

Changes

Cohort / File(s)	Summary
YAML Docs Generator annot/src/main/java/com/predic8/membrane/annot/generator/YamlDocsGenerator.java	New class that collects Model documentation by namespace and writes a deterministic docs.yaml to CLASS_OUTPUT using a YAML ObjectMapper; handles duplicate file creation gracefully.
Processor Integration annot/src/main/java/com/predic8/membrane/annot/SpringConfigurationXSDGeneratingAnnotationProcessor.java	Invokes YamlDocsGenerator.write(Model) in the main processing flow, positioned alongside existing docs/parsers generation steps.
Doc entry ordering annot/src/main/java/com/predic8/membrane/annot/model/doc/Doc.java	Replaces POSITIVE key ordering with a PRIORITY-based comparator (with fallback priority for unknown keys), uses isEmpty() for emptiness checks, and removes the unknown-tag warning path.

Sequence Diagram

sequenceDiagram
    participant APT as Annotation Processor
    participant YDG as YamlDocsGenerator
    participant Model as Model
    participant Filer as Filer

    APT->>YDG: write(model)
    YDG->>Model: read namespaces & element docs
    Model-->>YDG: return documentation model
    YDG->>YDG: build YAML structure (docFormatVersion, schemas...)
    YDG->>Filer: createSourceFile("docs.yaml")
    alt file exists -> FilerException
        Filer-->>YDG: throw FilerException
        YDG->>YDG: suppress / no-op on duplicate
    else success
        Filer->>Filer: write YAML content
        Filer-->>YDG: write complete
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• add yaml annot for documentation #2334: Edits the Doc parsing/ordering logic related to YAML doc generation and tag handling.

Suggested reviewers

• predic8
• rrayst

Poem

"I nibble notes and tidy tags all day,
YAML leaves in tidy rows I lay.
Priority hops, entries align,
Docs emerge, all neat and fine.
Hooray — a rabbit's tidy play!" 🐇✨

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'add generator to extract javadoc in separate yaml' accurately summarizes the main change: introducing YamlDocsGenerator to extract and generate YAML documentation from annotated elements.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into master

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch move-constants-to-yaml

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

annot/src/main/java/com/predic8/membrane/annot/generator/YamlDocsGenerator.java (1)

138-140: Nit: isHasAnyDoc → hasAnyDoc.

The is prefix combined with has is redundant. hasAnyDoc reads more naturally and follows Java naming conventions for boolean-returning methods.

Suggested rename

-    private static boolean isHasAnyDoc(Map<String, String> elementDoc, Map<String, Map<String, String>> attrs, Map<String, Map<String, String>> children, Map<String, String> otherAttrs) {
+    private static boolean hasAnyDoc(Map<String, String> elementDoc, Map<String, Map<String, String>> attrs, Map<String, Map<String, String>> children, Map<String, String> otherAttrs) {
         return !elementDoc.isEmpty() || !attrs.isEmpty() || !children.isEmpty() || !otherAttrs.isEmpty();
     }

And update the call site on line 132:

-            if (!isHasAnyDoc(elementDoc, attrs, children, otherAttrs)) continue;
+            if (!hasAnyDoc(elementDoc, attrs, children, otherAttrs)) continue;

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[christiangoerdes]

/ok-to-test

[membrane-ci-server]

This pull request needs "/ok-to-test" from an authorized committer.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In
`@annot/src/main/java/com/predic8/membrane/annot/generator/YamlDocsGenerator.java`:
- Around line 42-45: The catch block in YamlDocsGenerator currently relies on
the exact FilerException message ("Source file already created"), which is
brittle; update the catch(FilerException e) in YamlDocsGenerator to remove the
message.contains check and instead handle the exception unconditionally for the
duplicate-resource case: log a concise note (including the exception) via the
existing logger or processLogger and return/skip further processing, so
legitimate duplicate creation is silently handled while still recording the
exception details for debugging.
- Around line 123-127: writeScalar currently may emit its own trailing newline
for block scalars which causes callers like writeRoot and writeDocBlock to add
an extra blank line; change writeScalar to return a boolean (e.g.,
wroteTrailingNewline) that is true when it already emitted the trailing newline,
and update callers (writeRoot, writeDocBlock) to only call w.write("\n") when
writeScalar returned false. Ensure the new boolean is used wherever writeScalar
is invoked so single-line and multi-line scalars produce exactly one separating
newline.

🧹 Nitpick comments (4)

annot/src/main/java/com/predic8/membrane/annot/model/doc/Doc.java (1)

107-127: Removal of the unknown-tag warning is intentional but worth noting.

The old code warned when a Javadoc tag wasn't in the known-positive list. Now any tag not in NEGATIVE is accepted silently. This is fine if the intent is to allow arbitrary custom tags (e.g., @yaml), but it means typos in tag names (e.g., @descrption) will no longer produce a warning.

annot/src/main/java/com/predic8/membrane/annot/generator/YamlDocsGenerator.java (3)

181-252: The multi-line block-scalar logic is complex — consider simplifying or adding tests.

The indentation-stripping heuristic (lines 195–226) with firstNonBlank, minAll, minRest, and skipFirst is non-trivial. A couple of observations:

1. If every line is blank, firstNonBlank stays -1 and minAll becomes 0 (line 208). The block scalar then emits only indented blank lines — which is fine, but the | output would yield just whitespace.
2. The skipFirst path (lines 213–226) only activates when the first non-blank line has zero leading spaces while subsequent lines are indented. This re-indents everything except that first line, which is correct for typical Javadoc but hard to follow without comments.

Adding a few unit tests for representative inputs (plain single-line, multi-line with varying indentation, all-blank) would help safeguard this logic.

---

260-278: yamlKey: the YAML_11_RESERVED guard on ~ is unreachable.

~ doesn't match SIMPLE_KEY ([A-Za-z0-9_]+), so it's already quoted before reaching the reserved-word check. Not a bug — just dead-code noise in the set.

---

18-291: Hand-rolled YAML emitter — acceptable here, but consider a library if complexity grows.

For the current controlled output (no anchors, aliases, flow mappings, etc.) the manual approach works. If the format evolves (e.g., lists, more nesting, user-supplied keys with exotic characters), switching to a lightweight YAML library like SnakeYAML would reduce surface area for formatting bugs.