issue #520: JavaDoc & cleanups

PebbleTemplates · Dec 12, 2020 · 4c43484 · 4c43484
1 parent ede07f4
commit 4c43484
Show file tree

Hide file tree

Showing 4 changed files with 23 additions and 8 deletions.
diff --git a/pebble/src/main/java/com/mitchellbosecke/pebble/PebbleEngine.java b/pebble/src/main/java/com/mitchellbosecke/pebble/PebbleEngine.java
@@ -298,7 +298,7 @@ public static class Builder {
 
     private MethodAccessValidator methodAccessValidator = new BlacklistMethodAccessValidator();
 
-    private ExtensionRegistryFactory factory = new ExtensionRegistryFactory();
+    private final ExtensionRegistryFactory factory = new ExtensionRegistryFactory();
 
     /**
      * Creates the builder.
@@ -558,14 +558,13 @@ public Builder greedyMatchMethod(boolean greedyMatchMethod) {
     }
 
     /**
-     * Registeres a customizer which is called before the core functionality provided by default is registered
-     * into the {@link PebbleEngine}.
+     * Registeres an implementation of {@link ExtensionCustomizer} to change runtime-behaviour of standard
+     * functionality.
      *
-     * @param customizer The customizer which is called before registering the target extension
-     * @param <T>
+     * @param customizer The customizer which wraps any non-user-provided extension
      * @return This build object
      */
-    public <T extends Extension> Builder registerExtensionCustomizer(Function<Extension, ExtensionCustomizer> customizer) {
+    public Builder registerExtensionCustomizer(Function<Extension, ExtensionCustomizer> customizer) {
       this.factory.registerExtensionCustomizer(customizer);
       return this;
     }

diff --git a/pebble/src/main/java/com/mitchellbosecke/pebble/extension/ExtensionCustomizer.java b/pebble/src/main/java/com/mitchellbosecke/pebble/extension/ExtensionCustomizer.java
@@ -8,6 +8,19 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ *  Base class that allows implementing a customizer to modify Pebbles build-in extensions.
+ *  It is meant to provide a way to remove or replace functions, filters, tags, etc. to change
+ *  the standard behaviour. Use-cases can be down-stripping available functionality for security
+ *  reasons.
+ *
+ *  Implementations of this class are meant to overwrite methods and access registered functionality
+ *  before it is loaded into the PebbleEngine by calling super.
+ *
+ *  The ExentsionCustomizer can be registred via {@link com.mitchellbosecke.pebble.PebbleEngine.Builder#registerExtensionCustomizer}
+ *  and is applied for every non-user-provided extension.
+ *
+ */
 public abstract class ExtensionCustomizer implements Extension {
 
   private final Extension delegate;

diff --git a/pebble/src/main/java/com/mitchellbosecke/pebble/extension/ExtensionRegistryFactory.java b/pebble/src/main/java/com/mitchellbosecke/pebble/extension/ExtensionRegistryFactory.java
@@ -10,6 +10,11 @@
 import java.util.function.Function;
 import java.util.stream.Stream;
 
+/**
+ * Provides configuration methods and builds the {@link ExtensionRegistry}. Used only internally by
+ * the {@link com.mitchellbosecke.pebble.PebbleEngine.Builder}.
+ *
+ */
 public class ExtensionRegistryFactory {
 
   private final List<Extension> userProvidedExtensions = new ArrayList<>();

diff --git a/pebble/src/test/java/com/mitchellbosecke/pebble/extension/ExtensionCustomizerTest.java b/pebble/src/test/java/com/mitchellbosecke/pebble/extension/ExtensionCustomizerTest.java
@@ -2,14 +2,12 @@
 
 import com.mitchellbosecke.pebble.PebbleEngine;
 import com.mitchellbosecke.pebble.error.PebbleException;
-import com.mitchellbosecke.pebble.extension.core.CoreExtension;
 import com.mitchellbosecke.pebble.template.PebbleTemplate;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
 import java.io.IOException;
 import java.io.StringWriter;
-import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.Optional;