You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2023/12/17 19:16:21 UTC
(commons-digester) 02/03: Fix Javadoc errors
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-digester.git
commit 19d1789f2e1b979bd19a084fde206daa89e2e8d6
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Sun Dec 17 14:15:50 2023 -0500
Fix Javadoc errors
---
.../apache/commons/digester3/CallParamRule.java | 10 ++-----
.../commons/digester3/ExtendedBaseRules.java | 25 ++++++++--------
.../apache/commons/digester3/ObjectParamRule.java | 9 ++----
.../commons/digester3/SetNestedPropertiesRule.java | 33 ++++++++++++----------
.../commons/digester3/SetPropertiesRule.java | 28 +++++++++---------
.../commons/digester3/SimpleRegexMatcher.java | 12 ++------
.../org/apache/commons/digester3/StackAction.java | 6 ++--
.../digester3/WithDefaultsRulesWrapper.java | 12 ++------
8 files changed, 54 insertions(+), 81 deletions(-)
diff --git a/commons-digester3-core/src/main/java/org/apache/commons/digester3/CallParamRule.java b/commons-digester3-core/src/main/java/org/apache/commons/digester3/CallParamRule.java
index 7fe087e2..085c48ee 100644
--- a/commons-digester3-core/src/main/java/org/apache/commons/digester3/CallParamRule.java
+++ b/commons-digester3-core/src/main/java/org/apache/commons/digester3/CallParamRule.java
@@ -26,24 +26,22 @@ import org.xml.sax.Attributes;
/**
* <p>
- * Rule implementation that saves a parameter for use by a surrounding <code>CallMethodRule<code>.
+ * Rule implementation that saves a parameter for use by a surrounding {@link CallMethodRule}.
* </p>
* <p>
* This parameter may be:
+ * </p>
* <ul>
* <li>from an attribute of the current element See {@link #CallParamRule(int paramIndex, String attributeName)}
* <li>from current the element body See {@link #CallParamRule(int paramIndex)}
* <li>from the top object on the stack. See {@link #CallParamRule(int paramIndex, boolean fromStack)}
* <li>the current path being processed (separate {@code Rule}). See {@link PathCallParamRule}
* </ul>
- * </p>
*/
public class CallParamRule
extends Rule
{
- // ----------------------------------------------------------- Constructors
-
/**
* The attribute from which to save the parameter value
*/
@@ -64,8 +62,6 @@ public class CallParamRule
*/
protected int stackIndex;
- // ----------------------------------------------------- Instance Variables
-
/**
* Stack is used to allow nested body text to be processed. Lazy creation.
*/
@@ -125,8 +121,6 @@ public class CallParamRule
this.attributeName = attributeName;
}
- // --------------------------------------------------------- Public Methods
-
/**
* {@inheritDoc}
*/
diff --git a/commons-digester3-core/src/main/java/org/apache/commons/digester3/ExtendedBaseRules.java b/commons-digester3-core/src/main/java/org/apache/commons/digester3/ExtendedBaseRules.java
index 5a037827..984d8f59 100644
--- a/commons-digester3-core/src/main/java/org/apache/commons/digester3/ExtendedBaseRules.java
+++ b/commons-digester3-core/src/main/java/org/apache/commons/digester3/ExtendedBaseRules.java
@@ -38,10 +38,11 @@ import org.xml.sax.Attributes;
* It is intended to be a minimal extension of the standard rules big enough to support complex schema but without the
* full generality offered by more exotic matching pattern rules.
* </p>
- * <h4>When should you use this rather than the original?</h4>
+ * <h2>When should you use this rather than the original?</h2>
* <p>
* This pattern-matching engine is complex and slower than the basic default RulesBase class, but offers more
* functionality:
+ * </p>
* <ul>
* <li>Universal patterns allow patterns to be specified which will match regardless of whether there are
* "better matching" patterns available.</li>
@@ -50,8 +51,7 @@ import org.xml.sax.Attributes;
* depth.</li>
* <li>Completely-wild patterns ("*" or "!*") allow matching all elements.</li>
* </ul>
- * </p>
- * <h4>Universal Match Patterns</h4>
+ * <h2>Universal Match Patterns</h2>
* <p>
* The default RulesBase pattern-matching engine always attempts to find the "best matching pattern", and will ignore
* rules associated with other patterns that match but are not "as good". As an example, if the pattern "a/b/c" is
@@ -81,9 +81,10 @@ import org.xml.sax.Attributes;
* <li>Pattern {@code "!*/a/b/*"} matches any elements whose path contains 'a/b' (see
* "Ancestor Match Patterns").</li>
* </ul>
- * <h4>Parent Match Patterns</h4>
+ * <h2>Parent Match Patterns</h2>
* <p>
* These will match direct child elements of a particular parent element.
+ * </p>
* <ul>
* <li>
* {@code "a/b/c/?"} matches any child whose parent matches {@code "a/b/c"}. Exact parent rules take
@@ -93,10 +94,10 @@ import org.xml.sax.Attributes;
* matching still applies to parent matches but the length excludes the '?', which effectively means that standard
* wildcard matches with the same level of depth are chosen in preference.</li>
* </ul>
- * </p>
- * <h4>Ancestor Match Patterns</h4>
+ * <h2>Ancestor Match Patterns</h2>
* <p>
* These will match elements whose parentage includes a particular sequence of elements.
+ * </p>
* <ul>
* <li>
* {@code "a/b/*"} matches any element whose path starts with 'a' then 'b'. Exact parent and parent match rules
@@ -105,26 +106,25 @@ import org.xml.sax.Attributes;
* {@code "*/a/b/*"} matches any elements whose path contains an element 'a' followed by an element 'b'.
* The longest matching still applies but the length excludes the '*' at the end.</li>
* </ul>
- * </p>
- * <h4>Completely Wild Patterns</h4>
+ * <h2>Completely Wild Patterns</h2>
* <p>
* Pattern {@code "*"} matches every pattern that isn't matched by any other basic rule.
* </p>
* <p>
* Pattern {@code "!*"} matches every pattern.
* </p>
- * <h4>Using The Extended Rules</h4>
+ * <h2>Using The Extended Rules</h2>
* <p>
* By default, a Digester instance uses a {@link RulesBase} instance as its pattern matching engine. To use an
* ExtendedBaseRules instance, call the Digester.setRules method before adding any Rule objects to the digester
* instance:
+ * </p>
*
* <pre>
* Digester digester = new Digester();
* digester.setRules( new ExtendedBaseRules() );
* </pre>
*
- * </p>
* <p>
* The most important thing to remember when using the extended rules is that universal and non-universal patterns are
* completely independent. Universal patterns are never affected by the addition of new patterns or the removal of
@@ -133,6 +133,7 @@ import org.xml.sax.Attributes;
* <strong>can</strong> be affected by the addition of new <em>non-universal</em> patterns or the removal of existing
* <em>non-universal</em> patterns, because only rules associated with the "best matching" pattern for each xml element
* are executed.
+ * </p>
* <p>
* This means that you can use universal patterns to build up the simple parts of your structure - for example defining
* universal creation and property setting rules. More sophisticated and complex mapping will require non-universal
@@ -145,8 +146,6 @@ public class ExtendedBaseRules
extends RulesBase
{
- // ----------------------------------------------------- Instance Variables
-
/**
* Counts the entry number for the rules.
*/
@@ -158,8 +157,6 @@ public class ExtendedBaseRules
*/
private final Map<Rule, Integer> order = new HashMap<Rule, Integer>();
- // --------------------------------------------------------- Public Methods
-
/**
* Standard match. Matches the end of the pattern to the key.
*
diff --git a/commons-digester3-core/src/main/java/org/apache/commons/digester3/ObjectParamRule.java b/commons-digester3-core/src/main/java/org/apache/commons/digester3/ObjectParamRule.java
index 3951cb60..ca398311 100644
--- a/commons-digester3-core/src/main/java/org/apache/commons/digester3/ObjectParamRule.java
+++ b/commons-digester3-core/src/main/java/org/apache/commons/digester3/ObjectParamRule.java
@@ -25,17 +25,17 @@ import org.xml.sax.Attributes;
/**
* <p>
- * Rule implementation that saves a parameter for use by a surrounding <code>CallMethodRule<code>.
+ * Rule implementation that saves a parameter for use by a surrounding {@link CallMethodRule}.
* </p>
* <p>
* This parameter may be:
+ * </p>
* <ul>
* <li>an arbitrary Object defined programatically, assigned when the element pattern associated with the Rule is
* matched. See {@link #ObjectParamRule(int paramIndex, Object param)}.
* <li>an arbitrary Object defined programatically, assigned if the element pattern AND specified attribute name are
* matched. See {@link #ObjectParamRule(int paramIndex, String attributeName, Object param)}.
* </ul>
- * </p>
*
* @since 1.4
*/
@@ -52,14 +52,11 @@ public class ObjectParamRule
*/
protected int paramIndex;
- // ----------------------------------------------------- Instance Variables
-
/**
* The parameter we wish to pass to the method call
*/
protected Object param;
- // ----------------------------------------------------------- Constructors
/**
* Constructs a "call parameter" rule that will save the given Object as the parameter value.
*
@@ -86,8 +83,6 @@ public class ObjectParamRule
this.param = param;
}
- // --------------------------------------------------------- Public Methods
-
/**
* {@inheritDoc}
*/
diff --git a/commons-digester3-core/src/main/java/org/apache/commons/digester3/SetNestedPropertiesRule.java b/commons-digester3-core/src/main/java/org/apache/commons/digester3/SetNestedPropertiesRule.java
index c22dc7ad..ae9c11b9 100644
--- a/commons-digester3-core/src/main/java/org/apache/commons/digester3/SetNestedPropertiesRule.java
+++ b/commons-digester3-core/src/main/java/org/apache/commons/digester3/SetNestedPropertiesRule.java
@@ -341,9 +341,9 @@ public class SetNestedPropertiesRule
}
/**
- * Constructor which allows element->property mapping to be overridden.
+ * Constructor which allows element to property mapping to be overridden.
*
- * @param elementNames names of elements->properties to map
+ * @param elementNames names of elements to properties to map
* @since 3.0
*/
public SetNestedPropertiesRule( final Map<String, String> elementNames )
@@ -365,9 +365,9 @@ public class SetNestedPropertiesRule
* {@link #SetNestedPropertiesRule(String[] elementNames, String[] propertyNames)}.
* </p>
*
- * @param elementName is the child xml element to match
- * @param propertyName is the Java bean property to be assigned the value of the specified xml element. This may be
- * null, in which case the specified xml element will be ignored.
+ * @param elementName is the child XML element to match
+ * @param propertyName is the Java bean property to be assigned the value of the specified XML element. This may be
+ * null, in which case the specified XML element will be ignored.
*/
public SetNestedPropertiesRule( final String elementName, final String propertyName )
{
@@ -376,7 +376,7 @@ public class SetNestedPropertiesRule
/**
* <p>
- * Constructor which allows element->property mapping to be overridden.
+ * Constructor which allows element to property mapping to be overridden.
* </p>
* <p>
* Two arrays are passed in. One contains xml element names and the other Java bean property names. The element name
@@ -387,26 +387,28 @@ public class SetNestedPropertiesRule
* If a property name is null or the xml element name has no matching property name due to the arrays being of
* different lengths then this indicates that the xml element should be ignored.
* </p>
- * <h5>Example One</h5>
+ * <b>Example One</b>
* <p>
* The following constructs a rule that maps the {@code alt-city} element to the {@code city} property and
* the {@code alt-state} to the {@code state} property. All other child elements are mapped as usual using
- * exact name matching. <code><pre>
+ * exact name matching.
+ * </p>
+ * <pre>{@code
* SetNestedPropertiesRule(
* new String[] {"alt-city", "alt-state"},
* new String[] {"city", "state"});
- * </pre></code>
- * </p>
- * <h5>Example Two</h5>
+ * }</pre>
+ * <b>Example Two</b>
* <p>
* The following constructs a rule that maps the {@code class} xml element to the {@code className}
* property. The xml element {@code ignore-me} is not mapped, ie is ignored. All other elements are mapped as
- * usual using exact name matching. <code><pre>
+ * usual using exact name matching.
+ * </p>
+ * <pre>{@code
* SetPropertiesRule(
* new String[] {"class", "ignore-me"},
* new String[] {"className"});
- * </pre></code>
- * </p>
+ * }</pre>
*
* @param elementNames names of elements to map
* @param propertyNames names of properties mapped to
@@ -426,11 +428,12 @@ public class SetNestedPropertiesRule
}
/**
- * Add an additional custom xml-element -> property mapping.
+ * Add an additional custom xml-element to property mapping.
* <p>
* This is primarily intended to be used from the xml rules module (as it is not possible there to pass the
* necessary parameters to the constructor for this class). However it is valid to use this method directly if
* desired.
+ * </p>
*
* @param elementName the xml-element has to be mapped
* @param propertyName the property name target
diff --git a/commons-digester3-core/src/main/java/org/apache/commons/digester3/SetPropertiesRule.java b/commons-digester3-core/src/main/java/org/apache/commons/digester3/SetPropertiesRule.java
index 476a03ec..de4f6df2 100644
--- a/commons-digester3-core/src/main/java/org/apache/commons/digester3/SetPropertiesRule.java
+++ b/commons-digester3-core/src/main/java/org/apache/commons/digester3/SetPropertiesRule.java
@@ -43,8 +43,6 @@ public class SetPropertiesRule
extends Rule
{
- // ----------------------------------------------------------- Constructors
-
private final Map<String, String> aliases = new HashMap<String, String>();
/**
@@ -62,9 +60,9 @@ public class SetPropertiesRule
}
/**
- * Constructor allows attribute->property mapping to be overriden.
+ * Constructor allows attribute to property mapping to be overriden.
*
- * @param aliases attribute->property mapping
+ * @param aliases attribute to property mapping
* @since 3.0
*/
public SetPropertiesRule( final Map<String, String> aliases )
@@ -75,8 +73,6 @@ public class SetPropertiesRule
}
}
- // ----------------------------------------------------- Instance Variables
-
/**
* <p>
* Convenience constructor overrides the mapping for just one property.
@@ -96,7 +92,7 @@ public class SetPropertiesRule
/**
* <p>
- * Constructor allows attribute->property mapping to be overriden.
+ * Constructor allows attribute to property mapping to be overriden.
* </p>
* <p>
* Two arrays are passed in. One contains the attribute names and the other the property names. The attribute name /
@@ -107,24 +103,28 @@ public class SetPropertiesRule
* If a property name is null or the attribute name has no matching property name, then this indicates that the
* attibute should be ignored.
* </p>
- * <h5>Example One</h5>
+ * <b>Example One</b>
* <p>
* The following constructs a rule that maps the {@code alt-city} attribute to the {@code city} property
* and the {@code alt-state} to the {@code state} property. All other attributes are mapped as usual using
- * exact name matching. <code><pre>
+ * exact name matching.
+ * </p>
+ * <pre>{@code
* SetPropertiesRule(
* new String[] {"alt-city", "alt-state"},
* new String[] {"city", "state"});
- * </pre></code>
- * <h5>Example Two</h5>
+ * }</pre>
+ * <b>Example Two</b>
* <p>
* The following constructs a rule that maps the {@code class} attribute to the {@code className}
* property. The attribute {@code ignore-me} is not mapped. All other attributes are mapped as usual using
- * exact name matching. <code><pre>
+ * exact name matching.
+ * </p>
+ * <pre>{@code
* SetPropertiesRule(
* new String[] {"class", "ignore-me"},
* new String[] {"className"});
- * </pre></code>
+ * }</pre>
*
* @param attributeNames names of attributes to map
* @param propertyNames names of properties mapped to
@@ -143,8 +143,6 @@ public class SetPropertiesRule
}
}
- // --------------------------------------------------------- Public Methods
-
/**
* Add an additional attribute name to property name mapping. This is intended to be used from the xml rules.
*
diff --git a/commons-digester3-core/src/main/java/org/apache/commons/digester3/SimpleRegexMatcher.java b/commons-digester3-core/src/main/java/org/apache/commons/digester3/SimpleRegexMatcher.java
index 2ec5d5fc..590e28a7 100644
--- a/commons-digester3-core/src/main/java/org/apache/commons/digester3/SimpleRegexMatcher.java
+++ b/commons-digester3-core/src/main/java/org/apache/commons/digester3/SimpleRegexMatcher.java
@@ -28,11 +28,13 @@ import org.apache.commons.logging.LogFactory;
* </p>
* <p>
* This uses just two wildcards:
+ * </p>
* <ul>
* <li>{@code *} matches any sequence of none, one or more characters
* <li>{@code ?} matches any one character
* </ul>
- * Escaping these wildcards is not supported .
+ * <p>
+ * Escaping these wildcards is not supported.
* </p>
*
* @since 1.5
@@ -41,16 +43,12 @@ public class SimpleRegexMatcher
extends RegexMatcher
{
- // --------------------------------------------------------- Fields
-
/** Default log (class wide) */
private static final Log BASE_LOG = LogFactory.getLog( SimpleRegexMatcher.class );
/** Custom log (can be set per object) */
private Log log = BASE_LOG;
- // --------------------------------------------------------- Properties
-
/**
* Gets the {@code Log} implementation.
*
@@ -75,8 +73,6 @@ public class SimpleRegexMatcher
return match( basePattern, regexPattern, 0, 0 );
}
- // --------------------------------------------------------- Public Methods
-
/**
* Implementation of regex matching algorithm. This calls itself recursively.
*
@@ -167,8 +163,6 @@ public class SimpleRegexMatcher
}
}
- // --------------------------------------------------------- Implementations Methods
-
/**
* Sets the current {@code Log} implementation used by this class.
*
diff --git a/commons-digester3-core/src/main/java/org/apache/commons/digester3/StackAction.java b/commons-digester3-core/src/main/java/org/apache/commons/digester3/StackAction.java
index 0303c1a1..8b9717bb 100644
--- a/commons-digester3-core/src/main/java/org/apache/commons/digester3/StackAction.java
+++ b/commons-digester3-core/src/main/java/org/apache/commons/digester3/StackAction.java
@@ -26,11 +26,11 @@ package org.apache.commons.digester3;
* Because objects are pushed onto the main object stack when a rule has created a new object, this gives the ability to
* intercept such operations and perform modifications on created objects.
* <p>
- * One use expected for this interface is to store information about the xml line that a particular object was created
+ * One use expected for this interface is to store information about the XML line that a particular object was created
* from. An implementation of this interface can detect whenever an object is pushed onto the digester object stack,
- * call Digester.getDocumentLocator() to get the location within the current xml file, and store this either on the
+ * call Digester.getDocumentLocator() to get the location within the current XML file, and store this either on the
* object on the stack (if it supports some user-specific interface for this purpose), or build a map of
- * (object->locationinfo) separately.
+ * (object to locationinfo) separately.
* <p>
* It is recommended that objects implementing this interface provide a method to set a "next" action, and invoke it
* from the callback methods. This allows multiple actions to be "chained" together.
diff --git a/commons-digester3-core/src/main/java/org/apache/commons/digester3/WithDefaultsRulesWrapper.java b/commons-digester3-core/src/main/java/org/apache/commons/digester3/WithDefaultsRulesWrapper.java
index 46f53101..43606141 100644
--- a/commons-digester3-core/src/main/java/org/apache/commons/digester3/WithDefaultsRulesWrapper.java
+++ b/commons-digester3-core/src/main/java/org/apache/commons/digester3/WithDefaultsRulesWrapper.java
@@ -36,7 +36,7 @@ import org.xml.sax.Attributes;
* </p>
* <p>
* For example,
- *
+ * </p>
* <pre>
* Rule alpha;
* ...
@@ -46,7 +46,7 @@ import org.xml.sax.Attributes;
* digester.setRules(rules);
* ...
* </pre>
- *
+ * <p>
* when a pattern does not match any other rule, then rule alpha will be called.
* </p>
* <p>
@@ -59,8 +59,6 @@ public class WithDefaultsRulesWrapper
implements Rules
{
- // --------------------------------------------------------- Fields
-
/** The Rules implementation that this class wraps. */
private final Rules wrappedRules;
@@ -70,8 +68,6 @@ public class WithDefaultsRulesWrapper
/** All rules (preserves order in which they were originally added) */
private final List<Rule> allRules = new ArrayList<Rule>();
- // --------------------------------------------------------- Constructor
-
/**
* Base constructor.
*
@@ -86,8 +82,6 @@ public class WithDefaultsRulesWrapper
this.wrappedRules = wrappedRules;
}
- // --------------------------------------------------------- Properties
-
/**
* {@inheritDoc}
*/
@@ -150,8 +144,6 @@ public class WithDefaultsRulesWrapper
return wrappedRules.getDigester();
}
- // --------------------------------------------------------- Public Methods
-
/**
* {@inheritDoc}
*/