Doc (#270)

.mailmap

@@ -1,16 +1,16 @@
 Tom Hombergs <tom.hombergs@gmail.com>
 
-caring-coder <joseph@verron.pro>
-caring-coder <joseph@verron.pro> <3975735+josephverron@users.noreply.github.com>
-caring-coder <joseph@verron.pro> <joseph.verron@totalenergies.com>
-caring-coder <joseph@verron.pro> <joseph.verron@gmail.com>
+Joseph Verron <joseph@verron.pro>
+Joseph Verron <joseph@verron.pro> <3975735+josephverron@users.noreply.github.com>
+Joseph Verron <joseph@verron.pro> <joseph.verron@totalenergies.com>
+Joseph Verron <joseph@verron.pro> <joseph.verron@gmail.com>
 
-ynaciri <ynaciri@gmail.com>
-ynaciri <ynaciri@gmail.com> <youssouf.naciri@external.totalenergies.com>
-ynaciri <ynaciri@gmail.com> <95088722+AL1047088@users.noreply.github.com>
+Youssouf Naciri <ynaciri@gmail.com>
+Youssouf Naciri <ynaciri@gmail.com> <youssouf.naciri@external.totalenergies.com>
+Youssouf Naciri <ynaciri@gmail.com> <95088722+AL1047088@users.noreply.github.com>
 
-crivera <chris.rivera@taxfyle.com> <crivera@10.0.0.25>
-crivera <chris.rivera@taxfyle.com> <imbaroxxor@gmail.com>
-crivera <chris.rivera@taxfyle.com> <crivera@devconone.org>
+Chris Rivera <chris.rivera@taxfyle.com> <crivera@10.0.0.25>
+Chris Rivera <chris.rivera@taxfyle.com> <imbaroxxor@gmail.com>
+Chris Rivera <chris.rivera@taxfyle.com> <crivera@devconone.org>
 
 Mario Siegenthaler <m@riosiegenthaler.ch> <mario.siegenthaler@linkyard.ch>

commit-msg

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+
+# Create a regex for a conventional commit.
+conventional_commit_regex="^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z \-]+\))?!?: .+$"
+
+# Get the commit message (the parameter we're given is just the path to the
+# temporary file which holds the message).
+commit_message=$(cat "$1")
+
+# Check the message, if we match, all good baby.
+if [[ "$commit_message" =~ $conventional_commit_regex ]]; then
+   echo -e "\e[32mCommit message meets Conventional Commit standards...\e[0m"
+   exit 0
+fi
+
+# Uh-oh, this is not a conventional commit, show an example and link to the spec.
+echo -e "\e[31mThe commit message does not meet the Conventional Commit standard\e[0m"
+echo "An example of a valid message is: "
+echo "  feat(login): add the 'remember me' button"
+echo "More details at: https://www.conventionalcommits.org/en/v1.0.0/#summary"
+exit 1

scripts/doc/main-contributors.sh

@@ -0,0 +1,20 @@
+# This shell script looks for all Java files in the 'src' directory and its subdirectories
+# and then displays the top two contributors for each file.
+
+# Loops through each Java file found in the 'src' directory and its subdirectories.
+for java_file in $(find src -type f -name '*.java');
+do
+  # Uses 'git shortlog -ns' command to list contributors sorted by contribution quantity.
+  # The 'head -n 2' command only takes the top 2 contributors.
+  # The 'cut -c8-' command removes the initial part of each line that contains the number of commits.
+  # The 'tr '\n' ' '' command replaces the newline characters with spaces to format the output as a single line.
+  contributors=$(\
+    git shortlog -ns "$java_file" \
+    | head -n 2                   \
+    | cut -c8-                    \
+    | tr '\n' ' '                 \
+  );
+
+  # Prints the filename and contributors formatted as a line of output.
+  printf "%s %s\n" "$java_file" "$contributors";
+done

scripts/doc/original-version.sh

@@ -0,0 +1,17 @@
+# Recursive search in the 'src' directory for files (-type f) having '.java' extension
+find src -type f -name '*.java' |
+# Read each file in the returned list of '.java' files one by one
+while read -r java_file
+do
+  # Get the commit hash of the first commit where this file was introduced (using --follow to track renames).
+  # git log provides commit details, --follow flag helps with tracking file renames, --format=%h returns the commit hash
+  orig_commit_hash=$(git log --follow --format=%h "$java_file" | tail -n 1)
+
+  #  Using 'git show' to display the contents of 'pom.xml' from that commit.
+  #  Use xmlstarlet to extract the project version from the 'pom.xml' file.
+  #  xmlstarlet sel -t -v //_:project/_:version --nl : Selects the project version text from the XML, --nl adds a new line after each value
+  orig_project_version=$(git show "$orig_commit_hash:pom.xml" | xmlstarlet sel -t -v //_:project/_:version --nl)
+
+  # Print filename and its associated project version from the moment the file was first committed
+  echo "$java_file" "$orig_project_version"
+done

src/main/java/org/wickedsource/docxstamper/CommentProcessorBuilder.java

@@ -8,6 +8,7 @@
  *
  * @author Joseph Verron
  * @version ${version}
+ * @since 1.6.5
  */
 public interface CommentProcessorBuilder {
     /**

src/main/java/org/wickedsource/docxstamper/DocxStamper.java

@@ -28,8 +28,10 @@
  * The DocxStamper class is an implementation of the OpcStamper interface that is used to stamp DOCX templates with a context object and write the result to an output stream.
  *
  * @param <T> The type of the context that can be stamped
+ * @author Tom Hombergs
  * @author Joseph Verron
  * @version ${version}
+ * @since 1.0.0
  */
 public class DocxStamper<T> implements OpcStamper<WordprocessingMLPackage> {
 	private final List<PreProcessor> preprocessors;

src/main/java/org/wickedsource/docxstamper/DocxStamperConfiguration.java

@@ -28,6 +28,10 @@
  * The {@link DocxStamperConfiguration} class represents the configuration for
  * the {@link DocxStamper} class.
  * It provides methods to customize the behavior of the stamper.
+ * @author Joseph Verron
+ * @author Tom Hombergs
+ * @version ${version}
+ * @since 1.0.3
  */
 public class DocxStamperConfiguration {
 

src/main/java/org/wickedsource/docxstamper/api/DocxStamperException.java

@@ -5,7 +5,9 @@
  * It extends the RuntimeException class and provides additional constructors to handle different scenarios.
  *
  * @author Joseph Verron
+ * @author Tom Hombergs
  * @version ${version}
+ * @since 1.0.0
  */
 public class DocxStamperException extends RuntimeException {
 

src/main/java/org/wickedsource/docxstamper/api/EvaluationContextConfigurer.java

@@ -10,7 +10,9 @@
  * This can, for example, be used to add custom {@link PropertyAccessor}s and {@link MethodResolver}s.
  *
  * @author Joseph Verron
+ * @author Mario Siegenthaler
  * @version ${version}
+ * @since 1.0.13
  */
 public interface EvaluationContextConfigurer {
     /**

src/main/java/org/wickedsource/docxstamper/api/UnresolvedExpressionException.java

@@ -4,7 +4,9 @@
  * This exception is thrown if an expression could not be processed by any comment processor.
  *
  * @author Joseph Verron
+ * @author Tom Hombergs
  * @version ${version}
+ * @since 1.0.3
  */
 public class UnresolvedExpressionException extends DocxStamperException {
     /**

src/main/java/org/wickedsource/docxstamper/api/commentprocessor/ICommentProcessor.java

@@ -31,7 +31,9 @@
  * Register your comment processor in DocxStamper by calling DocxStamperConfiguration#addCommentProcessor().</p>
  *
  * @author Joseph Verron
+ * @author Tom Hombergs
  * @version ${version}
+ * @since 1.0.0
  */
 public interface ICommentProcessor {
 

src/main/java/org/wickedsource/docxstamper/api/preprocessor/PreProcessor.java

@@ -15,6 +15,7 @@
  * @see RemoveProofErrors
  * @author Joseph Verron
  * @version ${version}
+ * @since 1.6.4
  */
 public interface PreProcessor {
 	/**

src/main/java/org/wickedsource/docxstamper/api/typeresolver/ITypeResolver.java

@@ -20,7 +20,9 @@
  *
  * @param <T> the type of the object this type resolver is responsible for.
  * @author Joseph Verron
+ * @author Tom Hombergs
  * @version ${version}
+ * @since 1.0.0
  *
  * @deprecated as of version 1.6.7, replaced by {@link ObjectResolver}.
  * The new resolver is more versatile, requires less reflection mechanism,

src/main/java/org/wickedsource/docxstamper/el/DefaultEvaluationContextConfigurer.java

@@ -16,6 +16,7 @@
  *
  * @author Joseph Verron
  * @version ${version}
+ * @since 1.6.5
  */
 public class DefaultEvaluationContextConfigurer implements EvaluationContextConfigurer {
     /**

src/main/java/org/wickedsource/docxstamper/el/ExpressionResolver.java

@@ -10,7 +10,9 @@
  * expressions.
  *
  * @author Joseph Verron
+ * @author Tom Hombergs
  * @version ${version}
+ * @since 1.0.0
  */
 public class ExpressionResolver {
     private static final Matcher DEFAULT_MATCHER = new Matcher("${", "}");

src/main/java/org/wickedsource/docxstamper/el/ExpressionUtil.java

@@ -14,7 +14,9 @@
  * Utility class for working with expressions in a text.
  *
  * @author Joseph Verron
+ * @author Tom Hombergs
  * @version ${version}
+ * @since 1.0.0
  */
 public class ExpressionUtil {
 	private static final Pattern VARIABLE_EXPRESSION_PATTERN = Pattern.compile("\\$\\{(.*?)}");

src/main/java/org/wickedsource/docxstamper/el/Matcher.java

@@ -1,27 +1,32 @@
 package org.wickedsource.docxstamper.el;
 
+
+import org.springframework.lang.NonNull;
+
 /**
  * Represents a Matcher that checks if an expression starts with a specified prefix and ends with a specified suffix.
+ *
+ * @author Joseph Verron
+ * @version ${version}
+ * @since 1.6.5
  */
-public record Matcher(String prefix, String suffix) {
-    boolean match(String expression) {
-        assertNotNull(expression);
-        return expression.startsWith(prefix())
-               && expression.endsWith(suffix());
-    }
-
-    private static void assertNotNull(String expression) {
-        if (expression == null)
-            throw new IllegalArgumentException("Cannot strip NULL expression!");
+public record Matcher(
+        @NonNull String prefix,
+        @NonNull String suffix
+) {
+    @NonNull
+    boolean match(@NonNull String expression) {
+        return expression.startsWith(prefix)
+               && expression.endsWith(suffix);
     }
 
     /**
      * Strips the prefix and suffix from the given expression.
      * @param expression the expression to strip.
      * @return the stripped expression.
      */
-    public String strip(String expression) {
-        assertNotNull(expression);
+    @NonNull
+    public String strip(@NonNull String expression) {
         int start = prefix.length();
         int end = expression.length() - suffix.length();
         return expression.substring(start, end);

src/main/java/org/wickedsource/docxstamper/el/NoOpEvaluationContextConfigurer.java

@@ -19,7 +19,9 @@
  * contain any dangerous injections.
 
  * @author Joseph Verron
+ * @author Mario Siegenthaler
  * @version ${version}
+ * @since 1.0.13
  */
 public class NoOpEvaluationContextConfigurer implements EvaluationContextConfigurer {
     /**

src/main/java/org/wickedsource/docxstamper/el/StandardMethodExecutor.java

@@ -14,6 +14,7 @@
  *
  * @author Joseph Verron
  * @version ${version}
+ * @since 1.6.2
  */
 public class StandardMethodExecutor implements MethodExecutor {
 

src/main/java/org/wickedsource/docxstamper/el/StandardMethodResolver.java

@@ -18,6 +18,7 @@
  *
  * @author Joseph Verron
  * @version ${version}
+ * @since 1.6.2
  */
 public class StandardMethodResolver implements MethodResolver {
 	private final Map<Class<?>, Object> commentProcessors;

src/main/java/org/wickedsource/docxstamper/preprocessor/MergeSameStyleRuns.java

@@ -18,6 +18,7 @@
  *
  * @author Joseph Verron
  * @version ${version}
+ * @since 1.6.4
  */
 public class MergeSameStyleRuns implements PreProcessor {
 

src/main/java/org/wickedsource/docxstamper/preprocessor/RemoveProofErrors.java

@@ -15,6 +15,7 @@
  *
  * @author Joseph Verron
  * @version ${version}
+ * @since 1.6.4
  */
 public class RemoveProofErrors implements PreProcessor {
 

src/main/java/org/wickedsource/docxstamper/processor/BaseCommentProcessor.java

@@ -14,7 +14,9 @@
  * Base class for comment processors. The current run and paragraph are set by the {@link DocxStamper} class.
  *
  * @author Joseph Verron
+ * @author Tom Hombergs
  * @version ${version}
+ * @since 1.0.0
  */
 public abstract class BaseCommentProcessor implements ICommentProcessor {
 

src/main/java/org/wickedsource/docxstamper/processor/CommentProcessingException.java

@@ -10,7 +10,9 @@
  * Thrown when an error occurs while processing a comment in the docx template.
  *
  * @author Joseph Verron
+ * @author Tom Hombergs
  * @version ${version}
+ * @since 1.0.0
  */
 public class CommentProcessingException extends DocxStamperException {
 

src/main/java/org/wickedsource/docxstamper/processor/CommentProcessorFactory.java

@@ -18,6 +18,7 @@
  *
  * @author Joseph Verron
  * @version ${version}
+ * @since 1.6.4
  */
 public class CommentProcessorFactory {
 	private final DocxStamperConfiguration configuration;

src/main/java/org/wickedsource/docxstamper/processor/CommentProcessorRegistry.java

@@ -31,7 +31,9 @@
  * {@link ICommentProcessor}.
  *
  * @author Joseph Verron
+ * @author Tom Hombergs
  * @version ${version}
+ * @since 1.0.0
  */
 public class CommentProcessorRegistry {
     private final Logger logger = LoggerFactory.getLogger(

src/main/java/org/wickedsource/docxstamper/processor/displayif/DisplayIfProcessor.java

@@ -18,7 +18,9 @@
  * Processor for the {@link IDisplayIfProcessor} comment.
  *
  * @author Joseph Verron
+ * @author Tom Hombergs
  * @version ${version}
+ * @since 1.0.0
  */
 public class DisplayIfProcessor extends BaseCommentProcessor implements IDisplayIfProcessor {
 

src/main/java/org/wickedsource/docxstamper/processor/displayif/IDisplayIfProcessor.java

@@ -4,7 +4,9 @@
  * Interface for processors that may be used to delete commented paragraphs or tables from the document, depending on a given condition.
  *
  * @author Joseph Verron
+ * @author Tom Hombergs
  * @version ${version}
+ * @since 1.0.0
  */
 public interface IDisplayIfProcessor {
 

src/main/java/org/wickedsource/docxstamper/processor/repeat/IParagraphRepeatProcessor.java

@@ -15,7 +15,9 @@
  * within each copy against the respective object.
  *
  * @author Joseph Verron
+ * @author Romain Lamarche
  * @version ${version}
+ * @since 1.0.0
  */
 public interface IParagraphRepeatProcessor {
 

src/main/java/org/wickedsource/docxstamper/processor/repeat/IRepeatDocPartProcessor.java

@@ -8,7 +8,9 @@
  * Within each copy of the row, all expressions are evaluated against one of the objects in the list.
  *
  * @author Joseph Verron
+ * @author Artem Medvedev
  * @version ${version}
+ * @since 1.0.0
  */
 public interface IRepeatDocPartProcessor {
 

src/main/java/org/wickedsource/docxstamper/processor/repeat/IRepeatProcessor.java

@@ -6,7 +6,9 @@
  * Interface for processors that can repeat a table row.
  *
  * @author Joseph Verron
+ * @author Tom Hombergs
  * @version ${version}
+ * @since 1.0.0
  */
 public interface IRepeatProcessor {
 

src/main/java/org/wickedsource/docxstamper/processor/repeat/ParagraphRepeatProcessor.java

@@ -25,7 +25,9 @@
  * clients.
  *
  * @author Joseph Verron
+ * @author Youssouf Naciri
  * @version ${version}
+ * @since 1.2.2
  */
 public class ParagraphRepeatProcessor extends BaseCommentProcessor implements IParagraphRepeatProcessor {
 	private final Supplier<? extends List<? extends P>> nullSupplier;

src/main/java/org/wickedsource/docxstamper/processor/repeat/ParagraphResolverDocumentWalker.java

@@ -12,6 +12,7 @@
  *
  * @author Joseph Verron
  * @version ${version}
+ * @since 1.4.7
  */
 public class ParagraphResolverDocumentWalker extends BaseDocumentWalker {
 	private final Object expressionContext;