From a699cba292a21ecd297c9ff7476cd3ce2c294767 Mon Sep 17 00:00:00 2001
From: Andreas Hager <andy@mazebert.com>
Date: Sat, 19 Nov 2022 06:29:22 +0100
Subject: [PATCH] Add javadoc for gg.jte.Content

---
 jte-runtime/src/main/java/gg/jte/Content.java | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/jte-runtime/src/main/java/gg/jte/Content.java b/jte-runtime/src/main/java/gg/jte/Content.java
index b11c7acb..bd00451e 100644
--- a/jte-runtime/src/main/java/gg/jte/Content.java
+++ b/jte-runtime/src/main/java/gg/jte/Content.java
@@ -1,5 +1,45 @@
 package gg.jte;
 
+/**
+ * This interface can be used to create reusable content blocks for templates through Java code.
+ *
+ * When using the content block shorthand <code>@`...`</code> in templates, behind the scenes an anonymous class of
+ * {@link Content} is created as well. For example:
+ * <pre>
+ *     !{var name = "world";}
+ *     !{var myContent = @`
+ *         Hello ${name}!
+ *         This is a reusable content block.
+ *     `;}
+ *
+ *     ${myContent}
+ *     ${myContent}
+ * </pre>
+ *
+ * Would be the same as:
+ * <pre>
+ *     public class MyContent implements Content {
+ *         private final String name;
+ *
+ *         public MyContent(String name) {
+ *             this.name = name;
+ *         }
+ *
+ *         &#64;Override
+ *         public void writeTo(TemplateOutput output) {
+ *             output.writeContent("Hello ");
+ *
+ *             // User provided content, must be output escaped!
+ *             output.writeUserContent(name);
+ *
+ *             output.writeContent("!\n This is a reusable content block.");
+ *         }
+ *     }
+ * </pre>
+ *
+ * While the above example doesn't make a lot of sense, {@link Content} can be a very powerful
+ * abstraction for complex tasks.
+ */
 public interface Content {
     void writeTo(TemplateOutput output);