(doc) misc javadoc updates

doxia-core/src/main/java/org/apache/maven/doxia/Doxia.java

@@ -41,24 +41,21 @@ 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 <code>newReader</code> 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;
 
     /**
      * Return a parser for the given <code>parserId</code>.
      *
-     * @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;

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 )
     /**
      * <p>isEmitComments.</p>
      *
-     * @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,17 +171,17 @@ 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 )
         throws ParseException
     {
         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 <code>secondParsing</code> 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()

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.
      *