Add components description

[christiangoerdes]

Summary by CodeRabbit

• Documentation
  • Simplified YAML/Bean configuration examples for improved clarity and readability (constructorArgs and properties shown as direct values)
  • Added Javadoc-style component documentation with usage examples and categorization for easier discovery
  • Minor comment text correction in example configuration for clearer wording

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c93bec7 and b21d1f6.

📒 Files selected for processing (2)

• annot/src/main/java/com/predic8/membrane/annot/generator/ComponentClassGenerator.java
• distribution/examples/configuration/apis.yaml

✅ Files skipped from review due to trivial changes (1)

• distribution/examples/configuration/apis.yaml

🚧 Files skipped from review as they are similar to previous changes (1)

• annot/src/main/java/com/predic8/membrane/annot/generator/ComponentClassGenerator.java

---

📝 Walkthrough

Walkthrough

Updated documentation/templates in annotation generators: YAML example snippets in BeanClassGenerator were flattened (removed nested wrappers) and a Javadoc YAML example block was added to ComponentClassGenerator; a small comment typo in an example YAML file was fixed. No behavior or API changes.

Changes

Cohort / File(s)	Summary
Annotation generator — Bean docs annot/src/main/java/com/predic8/membrane/annot/generator/BeanClassGenerator.java	Flattened example YAML in the Bean class template: removed nested constructorArg/property wrapper objects and replaced with direct value / name/value entries in the sample.
Annotation generator — Component docs annot/src/main/java/com/predic8/membrane/annot/generator/ComponentClassGenerator.java	Added a Javadoc-style YAML example block and descriptive comment above the Components class implementation (documentation only).
Examples — minor text fix distribution/examples/configuration/apis.yaml	Corrected a comment text from "referencable" to "referenceable" in an example component entry.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• add yaml annot for documentation #2334 — Adds YAML examples/documentation tag parsing changes; related to generated-template YAML docs.
• Improve yaml syntax: Use collapsed for suitable classes (Breaking Change) #2776 — Converts YAML examples to collapsed/inline form; relates to the flattened YAML examples here.

Suggested reviewers

• predic8
• rrayst

Poem

🐇 I hop through code and tidy cheer,
Snip nested wrappers, make examples clear,
A YAML nibble, a comment mend,
Docs shine bright — hop, patch, and send! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 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 (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add components description' directly reflects the primary change: adding documentation/description for components across multiple files.

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

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch components-description

---

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.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

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

41-53: Consider aligning the Bean doccomment with the new structured annotation style.

ComponentClassGenerator now uses @description, @yaml (with <pre><code> wrapping), and @topic tags. The Bean class comment still uses plain prose. If a doc-generation tool processes these tags, Bean will be missing structured metadata.

♻️ Suggested alignment

-                /**
-                 * Spring-like bean definition usable in YAML components:
-                 * components:
-                 *   <id>:
-                 *     bean:
-                 *       class: com.example.MyInterceptor
-                 *       scope: SINGLETON
-                 *       constructorArgs:
-                 *         - value: foo
-                 *       properties:
-                 *         - name: bar
-                 *           value: baz
-                 */
+                /**
+                 * `@description` Spring-like bean definition for use inside YAML <code>components</code>.
+                 * `@yaml` <pre><code>
+                 * components:
+                 *   <id>:
+                 *     bean:
+                 *       class: com.example.MyInterceptor
+                 *       scope: SINGLETON
+                 *       constructorArgs:
+                 *         - value: foo
+                 *       properties:
+                 *         - name: bar
+                 *           value: baz
+                 * </code></pre>
+                 * `@topic` 1. Proxies and Flow
+                 */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@annot/src/main/java/com/predic8/membrane/annot/generator/BeanClassGenerator.java`
around lines 41 - 53, Update the Bean Javadoc in BeanClassGenerator to match the
structured annotation style used by ComponentClassGenerator: replace the plain
prose block with `@description` summarizing the bean purpose, add an `@yaml` tag
containing the YAML example wrapped with <pre><code> ... </code></pre>, and
include an `@topic` tag (e.g., "components / bean") so doc-generation tools get
the same metadata; target the doccomment above the Bean class definition in
BeanClassGenerator.java (look for the comment block that currently shows the
YAML example) and mirror the tag names/format used by ComponentClassGenerator.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In
`@annot/src/main/java/com/predic8/membrane/annot/generator/ComponentClassGenerator.java`:
- Line 44: In ComponentClassGenerator (class ComponentClassGenerator), fix the
typo in the inline comment string "referencable" to "referenceable" (replace the
word in the comment that reads "log: {} # referencable plugin" so it becomes
"log: {} # referenceable plugin").

---

Nitpick comments:
In
`@annot/src/main/java/com/predic8/membrane/annot/generator/BeanClassGenerator.java`:
- Around line 41-53: Update the Bean Javadoc in BeanClassGenerator to match the
structured annotation style used by ComponentClassGenerator: replace the plain
prose block with `@description` summarizing the bean purpose, add an `@yaml` tag
containing the YAML example wrapped with <pre><code> ... </code></pre>, and
include an `@topic` tag (e.g., "components / bean") so doc-generation tools get
the same metadata; target the doccomment above the Bean class definition in
BeanClassGenerator.java (look for the comment block that currently shows the
YAML example) and mirror the tag names/format used by ComponentClassGenerator.

---

ℹ️ Review info

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6c5f687 and c93bec7.

📒 Files selected for processing (2)

• annot/src/main/java/com/predic8/membrane/annot/generator/BeanClassGenerator.java
• annot/src/main/java/com/predic8/membrane/annot/generator/ComponentClassGenerator.java

[membrane-ci-server]

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