From 8bfb5be7e4ff728ba1bc8a1c4a8e884a2f37bacc Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Tue, 30 Jun 2020 22:33:43 +0200 Subject: [PATCH] (doc) misc javadoc updates --- .../java/org/apache/maven/doxia/Doxia.java | 19 +++++------ .../maven/doxia/parser/AbstractParser.java | 32 +++++++++---------- .../maven/doxia/parser/AbstractXmlParser.java | 2 +- 3 files changed, 25 insertions(+), 28 deletions(-) diff --git a/doxia-core/src/main/java/org/apache/maven/doxia/Doxia.java b/doxia-core/src/main/java/org/apache/maven/doxia/Doxia.java index 837bdc28d..5741910ff 100644 --- a/doxia-core/src/main/java/org/apache/maven/doxia/Doxia.java +++ b/doxia-core/src/main/java/org/apache/maven/doxia/Doxia.java @@ -41,13 +41,11 @@ public interface Doxia * Parses the given source model using a parser with given id, * and emits Doxia events into the given sink. * - * @param source not null reader that provides the source document. - * You could use newReader methods from {@link org.codehaus.plexus.util.ReaderFactory}. - * @param parserId Identifier for the parser to use. - * @param sink A sink that consumes the Doxia events. - * @throws org.apache.maven.doxia.parser.manager.ParserNotFoundException - * if no parser could be found for the given id. - * @throws org.apache.maven.doxia.parser.ParseException if the model could not be parsed. + * @param source not null reader that provides the source document + * @param parserId identifier for the parser to use + * @param sink a sink that consumes the Doxia events + * @throws ParserNotFoundException if no parser could be found for the given id + * @throws ParseException if the model could not be parsed */ void parse( Reader source, String parserId, Sink sink ) throws ParserNotFoundException, ParseException; @@ -55,10 +53,9 @@ void parse( Reader source, String parserId, Sink sink ) /** * Return a parser for the given parserId. * - * @param parserId Identifier for the parser to use. - * @return the parser defining by parserId. - * @throws org.apache.maven.doxia.parser.manager.ParserNotFoundException - * if no parser could be found for the given id. + * @param parserId identifier for the parser to use + * @return the parser identified by parserId + * @throws ParserNotFoundException if no parser could be found for the given id */ Parser getParser( String parserId ) throws ParserNotFoundException; diff --git a/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java b/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java index 1745585c6..72100c6c4 100644 --- a/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java +++ b/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java @@ -101,7 +101,7 @@ public abstract class AbstractParser /** * {@inheritDoc} * - * @return a int. + * @return a int */ public int getType() { @@ -117,7 +117,7 @@ public void setEmitComments( boolean emitComments ) /** *

isEmitComments.

* - * @return a boolean. + * @return a boolean */ public boolean isEmitComments() { @@ -127,11 +127,11 @@ public boolean isEmitComments() /** * Execute a macro on the given sink. * - * @param macroId An id to lookup the macro. - * @param request The corresponding MacroRequest. - * @param sink The sink to receive the events. - * @throws org.apache.maven.doxia.macro.MacroExecutionException if an error occurred during execution. - * @throws org.apache.maven.doxia.macro.manager.MacroNotFoundException if the macro could not be found. + * @param macroId an id to lookup the macro + * @param request the corresponding MacroRequest + * @param sink the sink to receive the events + * @throws org.apache.maven.doxia.macro.MacroExecutionException if an error occurred during execution + * @throws org.apache.maven.doxia.macro.manager.MacroNotFoundException if the macro could not be found */ // Made public right now because of the structure of the APT parser and // all its inner classes. @@ -148,7 +148,7 @@ public void executeMacro( String macroId, MacroRequest request, Sink sink ) /** * Returns the current base directory. * - * @return The base directory. + * @return the base directory * @deprecated this does not work in multi-module builds, see DOXIA-373 */ protected File getBasedir() @@ -171,9 +171,9 @@ protected File getBasedir() * * Convenience method to parse an arbitrary string and emit events into the given sink. * - * @param string A string that provides the source input. - * @param sink A sink that consumes the Doxia events. - * @throws org.apache.maven.doxia.parser.ParseException if the string could not be parsed. + * @param string a string that provides the source input + * @param sink a sink that consumes the Doxia events + * @throws org.apache.maven.doxia.parser.ParseException if the string could not be parsed * @since 1.1 */ public void parse( String string, Sink sink ) @@ -181,7 +181,7 @@ public void parse( String string, Sink sink ) { parse( new StringReader( string ), sink ); } - + /** {@inheritDoc} */ @Override public void parse( Reader source, Sink sink, String reference ) @@ -193,7 +193,7 @@ public void parse( Reader source, Sink sink, String reference ) /** * Set secondParsing to true, if we need a second parsing. * - * @param second True for second parsing. + * @param second true for second parsing */ public void setSecondParsing( boolean second ) { @@ -203,7 +203,7 @@ public void setSecondParsing( boolean second ) /** * Indicates if we are currently parsing a second time. * - * @return true if we are currently parsing a second time. + * @return true if we are currently parsing a second time * @since 1.1 */ protected boolean isSecondParsing() @@ -237,7 +237,7 @@ protected Log getLog() /** * Gets the current {@link MacroManager}. * - * @return The current {@link MacroManager}. + * @return the current {@link MacroManager} * @since 1.1 */ protected MacroManager getMacroManager() @@ -260,7 +260,7 @@ protected void init() /** * The current Doxia version. * - * @return the current Doxia version as a String. + * @return the current Doxia version as a String * @since 1.2 */ protected static String doxiaVersion() diff --git a/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractXmlParser.java b/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractXmlParser.java index 224c1cf3a..fd615c153 100644 --- a/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractXmlParser.java +++ b/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractXmlParser.java @@ -153,7 +153,7 @@ public void parse( Reader source, Sink sink ) setSecondParsing( false ); init(); } - + /** * Initializes the parser with custom entities or other options. *