diff --git a/annot/src/main/java/com/predic8/membrane/annot/generator/BeanClassGenerator.java b/annot/src/main/java/com/predic8/membrane/annot/generator/BeanClassGenerator.java
index 75d9ddaa60..3b4a28a396 100644
--- a/annot/src/main/java/com/predic8/membrane/annot/generator/BeanClassGenerator.java
+++ b/annot/src/main/java/com/predic8/membrane/annot/generator/BeanClassGenerator.java
@@ -46,12 +46,10 @@ protected String getClassImpl() {
                  *       class: com.example.MyInterceptor
                  *       scope: SINGLETON
                  *       constructorArgs:
-                 *         - constructorArg:
-                 *             value: foo
+                 *         - value: foo
                  *       properties:
-                 *         - property:
-                 *             name: bar
-                 *             value: baz
+                 *         - name: bar
+                 *           value: baz
                  */
                 @MCElement(name = "bean")
                 public class Bean {
diff --git a/annot/src/main/java/com/predic8/membrane/annot/generator/ComponentClassGenerator.java b/annot/src/main/java/com/predic8/membrane/annot/generator/ComponentClassGenerator.java
index 83bba7f6d3..c9b87da544 100644
--- a/annot/src/main/java/com/predic8/membrane/annot/generator/ComponentClassGenerator.java
+++ b/annot/src/main/java/com/predic8/membrane/annot/generator/ComponentClassGenerator.java
@@ -36,6 +36,20 @@ protected String getClassImpl() {
                 
                 import java.util.Map;
                 
+                /**
+                 * @description Defines reusable, named components that can be referenced from other sections (e.g., via <code>$ref</code>).
+                 * @yaml <pre><code>
+                 * components:
+                 *   demoComponent: # id for the component
+                 *     log: {} # referenceable plugin
+                 * ---
+                 * api:
+                 *   port: 2000
+                 *   flow:
+                 *     - $ref: '#/components/demoComponent' # references the demo component
+                 * </code></pre>
+                 * @topic 1. Proxies and Flow
+                 */
                 @MCElement(name = "components", topLevel = true, component=false)
                 public class Components {
                 
diff --git a/distribution/examples/configuration/apis.yaml b/distribution/examples/configuration/apis.yaml
index 8dce64b295..c1bff405f1 100644
--- a/distribution/examples/configuration/apis.yaml
+++ b/distribution/examples/configuration/apis.yaml
@@ -37,7 +37,7 @@ global:
 components:
 
   demoComponent: # id for the component
-    log: {} # referencable plugin
+    log: {} # referenceable plugin
 
   jmx: # id for the bean
     bean: