Update javadoc for clarity and consistency (#267)

Improved the clarity and consistency of javadocs across the codebase.
This includes better use of the javadoc link feature and updating
phrasing and grammar for more precise descriptions.

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

@@ -1,19 +1,20 @@
 package org.wickedsource.docxstamper;
 
+import org.wickedsource.docxstamper.api.commentprocessor.ICommentProcessor;
 import org.wickedsource.docxstamper.replace.PlaceholderReplacer;
 
 /**
- * Factory interface for creating {@link org.wickedsource.docxstamper.api.commentprocessor.ICommentProcessor} instances.
+ * Factory interface for creating {@link ICommentProcessor} instances.
  *
  * @author Joseph Verron
  * @version ${version}
  */
 public interface CommentProcessorBuilder {
     /**
-     * Creates a {@link org.wickedsource.docxstamper.api.commentprocessor.ICommentProcessor} instance.
+     * Creates a {@link ICommentProcessor} instance.
      *
      * @param placeholderReplacer the placeholder replacer that should be used by the comment processor.
-     * @return a {@link org.wickedsource.docxstamper.api.commentprocessor.ICommentProcessor} instance.
+     * @return a {@link ICommentProcessor} instance.
      */
     Object create(PlaceholderReplacer placeholderReplacer);
 }

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

@@ -14,6 +14,7 @@
 import org.wickedsource.docxstamper.replace.PlaceholderReplacer;
 import org.wickedsource.docxstamper.replace.typeresolver.ObjectResolverRegistry;
 import pro.verron.docxstamper.OpcStamper;
+import pro.verron.docxstamper.StamperFactory;
 import pro.verron.docxstamper.api.ObjectResolver;
 
 import java.io.InputStream;
@@ -38,7 +39,7 @@ public class DocxStamper<T> implements OpcStamper<WordprocessingMLPackage> {
 	/**
 	 * Creates a new DocxStamper with the default configuration.
 	 *
-	 * @deprecated since 1.6.4, use {@link pro.verron.docxstamper.StamperFactory#newDocxStamper()} or {@link pro.verron.docxstamper.StamperFactory#nopreprocessingDocxStamper()} instead.
+	 * @deprecated since 1.6.4, use {@link StamperFactory#newDocxStamper()} or {@link StamperFactory#nopreprocessingDocxStamper()} instead.
 	 */
 	@Deprecated(since = "1.6.4", forRemoval = true)
 	public DocxStamper() {
@@ -160,7 +161,7 @@ private static TypedValue throwException(ReflectiveOperationException exception)
 	 * </ul>
 	 * <p>
 	 * If you need a wider vocabulary of methods available in the comments, you can create your own ICommentProcessor
-	 * and register it via getCommentProcessorRegistry().addCommentProcessor().
+	 * and register it via {@link DocxStamperConfiguration#addCommentProcessor(Class, CommentProcessorBuilder)}.
 	 * </p>
 	 */
 	public void stamp(InputStream template, Object contextRoot, OutputStream out) throws DocxStamperException {
@@ -176,7 +177,8 @@ public void stamp(InputStream template, Object contextRoot, OutputStream out) th
 	/**
 	 * {@inheritDoc}
 	 *
-	 * Same as stamp(InputStream, T, OutputStream) except that you may pass in a DOCX4J document as a template instead
+	 * Same as {@link #stamp(InputStream, Object, OutputStream)} except that you
+	 * may pass in a DOCX4J document as a template instead
 	 * of an InputStream.
 	 */
 	@Override

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

@@ -1,6 +1,9 @@
 package org.wickedsource.docxstamper;
 
+import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
+import org.springframework.expression.EvaluationContext;
 import org.springframework.expression.spel.SpelParserConfiguration;
+import org.wickedsource.docxstamper.api.DocxStamperException;
 import org.wickedsource.docxstamper.api.EvaluationContextConfigurer;
 import org.wickedsource.docxstamper.api.preprocessor.PreProcessor;
 import org.wickedsource.docxstamper.api.typeresolver.ITypeResolver;
@@ -22,7 +25,8 @@
 import static java.util.stream.Collectors.toMap;
 
 /**
- * The {@code DocxStamperConfiguration} class represents the configuration for the {@code DocxStamper} class.
+ * The {@link DocxStamperConfiguration} class represents the configuration for
+ * the {@link DocxStamper} class.
  * It provides methods to customize the behavior of the stamper.
  */
 public class DocxStamperConfiguration {
@@ -70,8 +74,8 @@ public DocxStamperConfiguration() {
      *
      * @return the {@link Optional} containing the default replacement value,
      * or an empty {@link Optional} if no default replacement value is found
-     * @deprecated This method is deprecated since version 1.6.7.
-     * You shouldn't have to use it, it was a crutch use for inner workinf of
+     * @deprecated This method's been deprecated since version 1.6.7.
+     * You shouldn't have to use it, it was a crutch use for inner working of
      * docx-stamper
      */
     @Deprecated(since = "1.6.7")
@@ -93,11 +97,11 @@ public boolean isFailOnUnresolvedExpression() {
     }
 
     /**
-     * If set to true, stamper will throw an {@link org.wickedsource.docxstamper.api.DocxStamperException}
+     * If set to true, stamper will throw an {@link DocxStamperException}
      * if a variable expression or processor expression within the document or within the comments is encountered that cannot be resolved. Is set to true by default.
      *
      * @param failOnUnresolvedExpression a boolean
-     * @return a {@link org.wickedsource.docxstamper.DocxStamperConfiguration} object
+     * @return a {@link DocxStamperConfiguration} object
      */
     public DocxStamperConfiguration setFailOnUnresolvedExpression(boolean failOnUnresolvedExpression) {
         this.failOnUnresolvedExpression = failOnUnresolvedExpression;
@@ -147,7 +151,7 @@ public DocxStamperConfiguration replaceNullValues(boolean replaceNullValues) {
      * Indicates the default value to use for expressions that doesn't resolve.
      *
      * @param unresolvedExpressionsDefaultValue value to use instead for expression that doesn't resolve
-     * @return a {@link org.wickedsource.docxstamper.DocxStamperConfiguration} object
+     * @return a {@link DocxStamperConfiguration} object
      * @see DocxStamperConfiguration#replaceUnresolvedExpressions
      */
     public DocxStamperConfiguration unresolvedExpressionsDefaultValue(String unresolvedExpressionsDefaultValue) {
@@ -156,22 +160,22 @@ public DocxStamperConfiguration unresolvedExpressionsDefaultValue(String unresol
     }
 
     /**
-     * Indicates if expressions that doesn't resolve should be replaced by a default value.
+     * Indicates if a default value should replace expressions that don't resolve.
      *
      * @param replaceUnresolvedExpressions true to replace null value expression with resolved value (which is null), false to leave the expression as is
-     * @return a {@link org.wickedsource.docxstamper.DocxStamperConfiguration} object
+     * @return a {@link DocxStamperConfiguration} object
      */
     public DocxStamperConfiguration replaceUnresolvedExpressions(boolean replaceUnresolvedExpressions) {
         this.replaceUnresolvedExpressions = replaceUnresolvedExpressions;
         return this;
     }
 
     /**
-     * If an error is caught while evaluating an expression the expression will be replaced with an empty string instead
+     * If an error is caught while evaluating an expression, the expression will be replaced with an empty string instead
      * of leaving the original expression in the document.
      *
      * @param leaveEmpty true to replace expressions with empty string when an error is caught while evaluating
-     * @return a {@link org.wickedsource.docxstamper.DocxStamperConfiguration} object
+     * @return a {@link DocxStamperConfiguration} object
      */
     public DocxStamperConfiguration leaveEmptyOnExpressionError(boolean leaveEmpty) {
         this.leaveEmptyOnExpressionError = leaveEmpty;
@@ -180,7 +184,8 @@ public DocxStamperConfiguration leaveEmptyOnExpressionError(boolean leaveEmpty)
 
     /**
      * <p>
-     * Registers the given ITypeResolver for the given class. The registered ITypeResolver's resolve() method will only
+     * Registers the given {@link ITypeResolver} for the given class. The
+     * registered {@link ITypeResolver#resolve(WordprocessingMLPackage, Object)} method will only
      * be called with objects of the specified class.
      * </p>
      * <p>
@@ -191,7 +196,7 @@ public DocxStamperConfiguration leaveEmptyOnExpressionError(boolean leaveEmpty)
      * @param resolvedType the class whose objects are to be passed to the given ITypeResolver.
      * @param resolver     the resolver to resolve objects of the given type.
      * @param <T>          the type resolved by the ITypeResolver.
-     * @return a {@link org.wickedsource.docxstamper.DocxStamperConfiguration} object
+     * @return a {@link DocxStamperConfiguration} object
      * @deprecated This method has been deprecated since version 1.6.7, and
      * it is scheduled for removal.
      * It's recommended to use the {@link DocxStamperConfiguration#addResolver(ObjectResolver)}
@@ -211,7 +216,7 @@ public <T> DocxStamperConfiguration addTypeResolver(
      * @param interfaceClass the interface whose methods should be exposed in the expression language.
      * @param implementation the implementation that should be called to evaluate invocations of the interface methods
      *                       within the expression language. Must implement the interface above.
-     * @return a {@link org.wickedsource.docxstamper.DocxStamperConfiguration} object
+     * @return a {@link DocxStamperConfiguration} object
      */
     public DocxStamperConfiguration exposeInterfaceToExpressionLanguage(
             Class<?> interfaceClass, Object implementation
@@ -226,7 +231,7 @@ public DocxStamperConfiguration exposeInterfaceToExpressionLanguage(
      *
      * @param interfaceClass          the Interface which is implemented by the commentProcessor.
      * @param commentProcessorFactory the commentProcessor factory generating the specified interface.
-     * @return a {@link org.wickedsource.docxstamper.DocxStamperConfiguration} object
+     * @return a {@link DocxStamperConfiguration} object
      */
     public DocxStamperConfiguration addCommentProcessor(
             Class<?> interfaceClass,
@@ -278,7 +283,7 @@ public boolean isLeaveEmptyOnExpressionError() {
     /**
      * <p>Getter for the field <code>unresolvedExpressionsDefaultValue</code>.</p>
      *
-     * @return a {@link java.lang.String} object
+     * @return a {@link String} object
      */
     public String getUnresolvedExpressionsDefaultValue() {
         return unresolvedExpressionsDefaultValue;
@@ -287,7 +292,7 @@ public String getUnresolvedExpressionsDefaultValue() {
     /**
      * <p>Getter for the field <code>lineBreakPlaceholder</code>.</p>
      *
-     * @return a {@link java.lang.String} object
+     * @return a {@link String} object
      */
     public String getLineBreakPlaceholder() {
         return lineBreakPlaceholder;
@@ -309,19 +314,19 @@ public DocxStamperConfiguration setLineBreakPlaceholder(String lineBreakPlacehol
     /**
      * <p>Getter for the field <code>evaluationContextConfigurer</code>.</p>
      *
-     * @return a {@link org.wickedsource.docxstamper.api.EvaluationContextConfigurer} object
+     * @return a {@link EvaluationContextConfigurer} object
      */
     public EvaluationContextConfigurer getEvaluationContextConfigurer() {
         return evaluationContextConfigurer;
     }
 
     /**
-     * Provides an {@link org.wickedsource.docxstamper.api.EvaluationContextConfigurer} which may change the configuration of a Spring
-     * {@link org.springframework.expression.EvaluationContext} which is used for evaluating expressions
+     * Provides an {@link EvaluationContextConfigurer} which may change the configuration of a Spring
+     * {@link EvaluationContext} which is used for evaluating expressions
      * in comments and text.
      *
      * @param evaluationContextConfigurer the configurer to use.
-     * @return a {@link org.wickedsource.docxstamper.DocxStamperConfiguration} object
+     * @return a {@link DocxStamperConfiguration} object
      */
     public DocxStamperConfiguration setEvaluationContextConfigurer(
             EvaluationContextConfigurer evaluationContextConfigurer
@@ -333,20 +338,20 @@ public DocxStamperConfiguration setEvaluationContextConfigurer(
     /**
      * <p>Getter for the field <code>spelParserConfiguration</code>.</p>
      *
-     * @return a {@link org.springframework.expression.spel.SpelParserConfiguration} object
+     * @return a {@link SpelParserConfiguration} object
      */
     public SpelParserConfiguration getSpelParserConfiguration() {
         return spelParserConfiguration;
     }
 
     /**
-     * Sets the {@link org.springframework.expression.spel.SpelParserConfiguration} to use for expression parsing.
+     * Sets the {@link SpelParserConfiguration} to use for expression parsing.
      * <p>
      * Note that this configuration will be used for all expressions in the document, including expressions in comments!
      * </p>
      *
      * @param spelParserConfiguration the configuration to use.
-     * @return a {@link org.wickedsource.docxstamper.DocxStamperConfiguration} object
+     * @return a {@link DocxStamperConfiguration} object
      */
     public DocxStamperConfiguration setSpelParserConfiguration(
             SpelParserConfiguration spelParserConfiguration
@@ -358,7 +363,7 @@ public DocxStamperConfiguration setSpelParserConfiguration(
     /**
      * <p>Getter for the field <code>expressionFunctions</code>.</p>
      *
-     * @return a {@link java.util.Map} object
+     * @return a {@link Map} object
      */
     public Map<Class<?>, Object> getExpressionFunctions() {
         return expressionFunctions;
@@ -368,7 +373,7 @@ public Map<Class<?>, Object> getExpressionFunctions() {
      * Retrieves the map of type resolvers.
      *
      * @return the map of type resolvers
-     * @deprecated This method is deprecated since version 1.6.7
+     * @deprecated This method's been deprecated since version 1.6.7
      */
     @Deprecated(since = "1.6.7", forRemoval = true)
     public Map<Class<?>, ITypeResolver<?>> getTypeResolvers() {
@@ -385,8 +390,8 @@ public Map<Class<?>, ITypeResolver<?>> getTypeResolvers() {
      * {@link ITypeResolver}, and returns the first one found. If no type resolver is found, null is returned.
      *
      * @return the default type resolver, or null if not found
-     * @deprecated This method is deprecated since version 1.6.7 and is scheduled for removal.
-     * You should not have to use it, it was a clutch for previosu version of
+     * @deprecated This method's been deprecated since version 1.6.7 and is scheduled for removal.
+     * You should not have to use it, it was a clutch for previous version of
      * docx-stamper.
      */
     @Deprecated(since = "1.6.7", forRemoval = true)
@@ -422,7 +427,7 @@ public DocxStamperConfiguration setDefaultTypeResolver(
     /**
      * <p>Getter for the field <code>commentProcessors</code>.</p>
      *
-     * @return a {@link java.util.Map} object
+     * @return a {@link Map} object
      */
     public Map<Class<?>, CommentProcessorBuilder> getCommentProcessors() {
         return commentProcessors;
@@ -432,7 +437,7 @@ public Map<Class<?>, CommentProcessorBuilder> getCommentProcessors() {
      * Gets the flag indicating whether null values should be replaced.
      *
      * @return {@code true} if null values should be replaced, {@code false} otherwise.
-     * @deprecated This method is deprecated since version 1.6.7 and will be removed in a future release.
+     * @deprecated This method's been deprecated since version 1.6.7 and will be removed in a future release.
      * You shouldn't have to use it, it was a clutch for
      * docx-stamper workings.
      */
@@ -456,7 +461,7 @@ public String getNullValuesDefault() {
     /**
      * <p>Getter for the field <code>preprocessors</code>.</p>
      *
-     * @return a {@link java.util.List} object
+     * @return a {@link List} object
      */
     public List<PreProcessor> getPreprocessors() {
         return preprocessors;

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

@@ -1,10 +1,13 @@
 package org.wickedsource.docxstamper.api;
 
+import org.springframework.expression.EvaluationContext;
+import org.springframework.expression.MethodResolver;
+import org.springframework.expression.PropertyAccessor;
 import org.springframework.expression.spel.support.StandardEvaluationContext;
 
 /**
- * Allows for custom configuration of a spring expression language {@link org.springframework.expression.EvaluationContext}.
- * This can  for example be used to add custom {@link org.springframework.expression.PropertyAccessor}s and {@link org.springframework.expression.MethodResolver}s.
+ * Allows for custom configuration of a spring expression language {@link EvaluationContext}.
+ * This can, for example, be used to add custom {@link PropertyAccessor}s and {@link MethodResolver}s.
  *
  * @author Joseph Verron
  * @version ${version}
@@ -13,7 +16,7 @@ public interface EvaluationContextConfigurer {
     /**
      * Configure the context before it's used by docxstamper.
      *
-     * @param context the spel eval context, not null
+     * @param context the SPEL eval context, not null
      */
     void configureEvaluationContext(StandardEvaluationContext context);
 }

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

@@ -38,15 +38,15 @@ public interface ICommentProcessor {
 	/**
 	 * This method is called after all comments in the .docx template have been passed to the comment processor.
 	 * All manipulations of the .docx document SHOULD BE done in this method. If certain manipulations are already done
-	 * within in the custom methods of a comment processor, the ongoing iteration over the paragraphs in the document
+	 * within the custom methods of a comment processor, the ongoing iteration over the paragraphs in the document
 	 * may be disturbed.
 	 *
 	 * @param document The Word document that can be manipulated by using the DOCX4J api.
 	 */
 	void commitChanges(WordprocessingMLPackage document);
 
 	/**
-	 * Passes the paragraph that is currently being processed (i.e. the paragraph that is commented in the
+	 * Passes the paragraph that is currently being processed (i.e., the paragraph that is commented in the
 	 * .docx template). This method is always called BEFORE the custom
 	 * methods of the custom comment processor interface
 	 * are called.
@@ -78,7 +78,7 @@ public interface ICommentProcessor {
 	/**
 	 * Passes the processed document, in order to make all linked data
 	 * (images, etc.) available
-	 * to processors that need it (example : repeatDocPart)
+	 * to processors that need it (example: repeatDocPart)
 	 *
 	 * @param document DocX template being processed.
 	 * @deprecated the document is passed to the processor through the commitChange method now,
@@ -89,7 +89,7 @@ public interface ICommentProcessor {
 	void setDocument(WordprocessingMLPackage document);
 
 	/**
-	 * Resets all state in the comment processor so that it can be re-used in another stamping process.
+	 * Resets all states in the comment processor so that it can be re-used in another stamping process.
 	 */
 	void reset();
 }

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

@@ -1,15 +1,18 @@
 package org.wickedsource.docxstamper.api.preprocessor;
 
 import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
+import org.wickedsource.docxstamper.DocxStamper;
+import org.wickedsource.docxstamper.preprocessor.MergeSameStyleRuns;
+import org.wickedsource.docxstamper.preprocessor.RemoveProofErrors;
 
 /**
  * The interface for all pre-processors. Pre-processors are called before the
  * document is processed by the DocxStamper. They can be used to manipulate the
  * document before the actual processing takes place.
  *
- * @see org.wickedsource.docxstamper.DocxStamper
- * @see org.wickedsource.docxstamper.preprocessor.MergeSameStyleRuns
- * @see org.wickedsource.docxstamper.preprocessor.RemoveProofErrors
+ * @see DocxStamper
+ * @see MergeSameStyleRuns
+ * @see RemoveProofErrors
  * @author Joseph Verron
  * @version ${version}
  */