refactor(core): Add javadoc to extensions API. Relates to #929

api/jreleaser-model-api/src/main/java/org/jreleaser/extensions/api/Extension.java

@@ -20,11 +20,31 @@
 import java.util.Set;
 
 /**
+ * Provides a collection of {@code ExtensionPoints}.
+ * <p>
+ * Every extension must define a unique name.
+ * <p>
+ * Extensions are loaded using the standard ServiceProvider mechanism,
+ * (see <a href="https://docs.oracle.com/javase/tutorial/sound/SPI-intro.html">
+ * https://docs.oracle.com/javase/tutorial/sound/SPI-intro.html</a>
+ * for more details).
+ *
  * @author Andres Almiray
  * @since 1.3.0
  */
 public interface Extension {
+    /**
+     * The given name of the extension.
+     *
+     * @return a non {@code null} String.
+     */
     String getName();
 
+    /**
+     * A collection of {@code ExtensionPoint} instances.
+     * <p>
+     *
+     * @return a non {@code null} collection.
+     */
     Set<? extends ExtensionPoint> provides();
 }

api/jreleaser-model-api/src/main/java/org/jreleaser/extensions/api/ExtensionPoint.java

@@ -20,10 +20,17 @@
 import java.util.Map;
 
 /**
+ * Defines an extension point for a given feature.
+ *
  * @author Andres Almiray
  * @since 1.3.0
  */
 public interface ExtensionPoint {
+    /**
+     * Initializes the extension point with values defined in the configuration DSL.
+     *
+     * @param properties a {@code Map} of key/value pairs.
+     */
     default void init(Map<String, Object> properties) {
         // noop
     }

api/jreleaser-model-api/src/main/java/org/jreleaser/extensions/api/mustache/MustacheExtensionPoint.java

@@ -22,9 +22,19 @@
 import java.util.Map;
 
 /**
+ * Enables customization of the Mustache context used when evaluating named templates.
+ *
  * @author Andres Almiray
  * @since 1.3.0
  */
 public interface MustacheExtensionPoint extends ExtensionPoint {
-    void apply(Map<String, Object> props);
+    /**
+     * Enhances the given context with additional properties.
+     * <p>
+     * <strong>WARNING: </strong> be careful when defining key names
+     * as you may override existing ones.
+     *
+     * @param context the evaluation context.
+     */
+    void apply(Map<String, Object> context);
 }

core/jreleaser-extensions-impl/src/main/java/org/jreleaser/extensions/impl/mustache/DefaultMustacheExtensionPoint.java

@@ -46,26 +46,26 @@
  * @since 1.3.0
  */
 public final class DefaultMustacheExtensionPoint implements MustacheExtensionPoint {
-    public void apply(Map<String, Object> props) {
-        ZonedDateTime now = (ZonedDateTime) props.get(Constants.KEY_ZONED_DATE_TIME_NOW);
+    public void apply(Map<String, Object> context) {
+        ZonedDateTime now = (ZonedDateTime) context.get(Constants.KEY_ZONED_DATE_TIME_NOW);
         if (null == now) {
             now = ZonedDateTime.now();
         }
-        props.put("f_now", new TimeFormatFunction(now));
-
-        props.put("f_trim", new TrimFunction());
-        props.put("f_underscore", new UnderscoreFunction());
-        props.put("f_dash", new DashFunction());
-        props.put("f_slash", new SlashFunction());
-        props.put("f_upper", new UpperFunction());
-        props.put("f_lower", new LowerFunction());
-        props.put("f_capitalize", new CapitalizeFunction());
-        props.put("f_uncapitalize", new UncapitalizeFunction());
-        props.put("f_md2html", new MarkdownToHtmlFunction());
-        props.put("f_file_read", new FileReadFunction());
-        props.put("f_file_size", new FileSizeFunction());
+        context.put("f_now", new TimeFormatFunction(now));
+
+        context.put("f_trim", new TrimFunction());
+        context.put("f_underscore", new UnderscoreFunction());
+        context.put("f_dash", new DashFunction());
+        context.put("f_slash", new SlashFunction());
+        context.put("f_upper", new UpperFunction());
+        context.put("f_lower", new LowerFunction());
+        context.put("f_capitalize", new CapitalizeFunction());
+        context.put("f_uncapitalize", new UncapitalizeFunction());
+        context.put("f_md2html", new MarkdownToHtmlFunction());
+        context.put("f_file_read", new FileReadFunction());
+        context.put("f_file_size", new FileSizeFunction());
         EnumSet.allOf(Algorithm.class)
-            .forEach(algorithm -> props.put("f_checksum_" + algorithm.formatted(), new FileChecksumFunction(algorithm)));
+            .forEach(algorithm -> context.put("f_checksum_" + algorithm.formatted(), new FileChecksumFunction(algorithm)));
     }