maven-doxia-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ltheu...@apache.org
Subject svn commit: r559578 [1/2] - in /maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia: ./ index/ macro/ macro/manager/ macro/snippet/ macro/toc/ parser/ parser/manager/ sink/ site/module/ site/module/manager/ util/
Date Wed, 25 Jul 2007 20:12:57 GMT
Author: ltheussl
Date: Wed Jul 25 13:12:56 2007
New Revision: 559578

URL: http://svn.apache.org/viewvc?view=rev&rev=559578
Log:
Javadocs. No code changes.

Modified:
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/DefaultDoxia.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/Doxia.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/index/IndexEntry.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/index/IndexingSink.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/EchoMacro.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/Macro.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/MacroExecutionException.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/MacroRequest.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/SwfMacro.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/manager/DefaultMacroManager.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/manager/MacroManager.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/manager/MacroNotFoundException.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/snippet/SnippetMacro.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/snippet/SnippetReader.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/toc/TocMacro.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/ParseException.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/Parser.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/manager/DefaultParserManager.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/manager/ParserManager.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/manager/ParserNotFoundException.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/sink/SinkAdapter.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/sink/StructureSink.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/AbstractSiteModule.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/SiteModule.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/manager/DefaultSiteModuleManager.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/manager/SiteModuleManager.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/manager/SiteModuleNotFoundException.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/ByLineReaderSource.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/FileUtil.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/LineBreaker.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/StringUtil.java
    maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/WrappedException.java

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/DefaultDoxia.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/DefaultDoxia.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/DefaultDoxia.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/DefaultDoxia.java Wed Jul 25 13:12:56 2007
@@ -28,6 +28,9 @@
 import java.io.Reader;
 
 /**
+ * Simple implementation of the Doxia interface:
+ * uses a ParserManager to lookup a parser.
+ *
  * @plexus.component
  *
  * @author Jason van Zyl
@@ -47,6 +50,7 @@
     // which can probably be done away with.
     // ----------------------------------------------------------------------
 
+    /** {@inheritDoc} */
     public void parse( Reader source, String parserId, Sink sink )
         throws ParserNotFoundException, ParseException
     {

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/Doxia.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/Doxia.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/Doxia.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/Doxia.java Wed Jul 25 13:12:56 2007
@@ -26,13 +26,27 @@
 import java.io.Reader;
 
 /**
+ * Basic interface of the Doxia framework.
+ *
  * @author Jason van Zyl
  * @version $Id:Doxia.java 348605 2005-11-24 12:02:44 +1100 (Thu, 24 Nov 2005) brett $
  */
 public interface Doxia
 {
+    /** The Plexus lookup role. */
     String ROLE = Doxia.class.getName();
 
+    /**
+     * Parses the given source model using a parser with given id,
+     * and emits Doxia events into the given sink.
+     *
+     * @param source A 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;
 

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/index/IndexEntry.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/index/IndexEntry.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/index/IndexEntry.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/index/IndexEntry.java Wed Jul 25 13:12:56 2007
@@ -32,78 +32,129 @@
  */
 public class IndexEntry
 {
+    /** The parent entry. */
     private IndexEntry parent;
 
+    /** The id of the entry. */
     private String id;
 
+    /** The entry title. */
     private String title;
 
+    /** The child entries. */
     private List childEntries = new ArrayList();
 
+    /** System-dependent EOL. */
     private static final String EOL = System.getProperty( "line.separator" );
 
-    public IndexEntry( String id )
+    /**
+     * Constructor.
+     *
+     * @param newId The id.
+     */
+    public IndexEntry( String newId )
+    {
+        this.id = newId;
+    }
+
+    /**
+     * Constructor.
+     *
+     * @param newParent The parent. Cannot be null.
+     * @param newId The id. Cannot be null.
+     */
+    public IndexEntry( IndexEntry newParent, String newId )
     {
-        this.id = id;
-    }
-
-    public IndexEntry( IndexEntry parent, String id )
-    {
-        if ( parent == null )
+        if ( newParent == null )
         {
             throw new NullPointerException( "parent cannot be null." );
         }
 
-        if ( id == null )
+        if ( newId == null )
         {
-            throw new NullPointerException( "parent cannot be null." );
+            throw new NullPointerException( "id cannot be null." );
         }
 
-        this.parent = parent;
-        this.id = id;
+        this.parent = newParent;
+        this.id = newId;
 
         parent.childEntries.add( this );
     }
 
+    /**
+     * Returns the parent entry.
+     *
+     * @return the parent entry.
+     */
     public IndexEntry getParent()
     {
         return parent;
     }
 
+    /**
+     * Returns the id.
+     *
+     * @return the id.
+     */
     public String getId()
     {
         return id;
     }
 
+    /**
+     * Returns the title.
+     *
+     * @return the title.
+     */
     public String getTitle()
     {
         return title;
     }
 
-    public void setTitle( String title )
-    {
-        this.title = title;
+    /**
+     * Sets the title.
+     *
+     * @param newTitle the title.
+     */
+    public void setTitle( String newTitle )
+    {
+        this.title = newTitle;
     }
 
+    /**
+     * Returns an unmodifiableList of the child entries.
+     *
+     * @return child entries.
+     */
     public List getChildEntries()
     {
         return Collections.unmodifiableList( childEntries );
     }
 
-    public void setChildEntries( List childEntries )
+    /**
+     * Sets the child entriesor creates a new ArrayList if entries == null.
+     *
+     * @param entries the entries.
+     */
+    public void setChildEntries( List entries )
     {
-        if ( childEntries == null )
+        if ( entries == null )
         {
             childEntries = new ArrayList();
         }
 
-        this.childEntries = childEntries;
+        this.childEntries = entries;
     }
 
     // -----------------------------------------------------------------------
     // Utils
     // -----------------------------------------------------------------------
 
+    /**
+     * Returns the next entry.
+     *
+     * @return the next entry, or null if there is none.
+     */
     public IndexEntry getNextEntry()
     {
         if ( parent == null )
@@ -123,6 +174,11 @@
         return (IndexEntry) entries.get( index + 1 );
     }
 
+    /**
+     * Returns the previous entry.
+     *
+     * @return the previous entry, or null if there is none.
+     */
     public IndexEntry getPrevEntry()
     {
         if ( parent == null )
@@ -142,6 +198,11 @@
         return (IndexEntry) entries.get( index - 1 );
     }
 
+    /**
+     * Returns the first entry.
+     *
+     * @return the first entry, or null if there is none.
+     */
     public IndexEntry getFirstEntry()
     {
         List entries = getChildEntries();
@@ -156,6 +217,11 @@
         }
     }
 
+    /**
+     * Returns the last entry.
+     *
+     * @return the last entry, or null if there is none.
+     */
     public IndexEntry getLastEntry()
     {
         List entries = getChildEntries();
@@ -170,6 +236,11 @@
         }
     }
 
+    /**
+     * Returns the root entry.
+     *
+     * @return the root entry, or null if there is none.
+     */
     public IndexEntry getRootEntry()
     {
         List entries = getChildEntries();
@@ -192,11 +263,22 @@
     // Object Overrides
     // -----------------------------------------------------------------------
 
+    /**
+     * Returns a string representation of the object.
+     *
+     * @return A string.
+     */
     public String toString()
     {
         return toString( 0 );
     }
 
+    /**
+     * Returns a string representation of all objects to the given depth.
+     *
+     * @param depth The depth to descent to.
+     * @return A string.
+     */
     public String toString( int depth )
     {
         StringBuffer message = new StringBuffer();

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/index/IndexingSink.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/index/IndexingSink.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/index/IndexingSink.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/index/IndexingSink.java Wed Jul 25 13:12:56 2007
@@ -34,34 +34,46 @@
 public class IndexingSink
     extends SinkAdapter
 {
-    private final static int TYPE_SECTION_1 = 1;
+    /** Section 1. */
+    private static final int TYPE_SECTION_1 = 1;
 
-    private final static int TYPE_SECTION_2 = 2;
+    /** Section 2. */
+    private static final int TYPE_SECTION_2 = 2;
 
-    private final static int TYPE_SECTION_3 = 3;
+    /** Section 3. */
+    private static final int TYPE_SECTION_3 = 3;
 
-    private final static int TYPE_SECTION_4 = 4;
+    /** Section 4. */
+    private static final int TYPE_SECTION_4 = 4;
 
-    private final static int TYPE_SECTION_5 = 5;
+    /** Section 5. */
+    private static final int TYPE_SECTION_5 = 5;
 
-    private final static int TYPE_DEFINED_TERM = 6;
+    /** Defined term. */
+    private static final int TYPE_DEFINED_TERM = 6;
 
-    private final static int TYPE_FIGURE = 7;
+    /** Figure. */
+    private static final int TYPE_FIGURE = 7;
 
-    private final static int TYPE_TABLE = 8;
+    /** Table. */
+    private static final int TYPE_TABLE = 8;
 
-    private final static int TITLE = 9;
+    /** Title. */
+    private static final int TITLE = 9;
 
+    /** The current type. */
     private int type;
 
+    /** The current title. */
     private String title;
 
+    /** The stack. */
     private Stack stack = new Stack();
 
     /**
-     * Default constructor
+     * Default constructor.
      *
-     * @param sectionEntry
+     * @param sectionEntry The first index entry.
      */
     public IndexingSink( IndexEntry sectionEntry )
     {
@@ -80,6 +92,7 @@
     // Sink Overrides
     // ----------------------------------------------------------------------
 
+    /** {@inheritDoc} */
     public void title()
     {
         super.title();
@@ -87,51 +100,61 @@
         type = TITLE;
     }
 
+    /** {@inheritDoc} */
     public void sectionTitle1()
     {
         type = TYPE_SECTION_1;
     }
 
+    /** {@inheritDoc} */
     public void section1_()
     {
         pop();
     }
 
+    /** {@inheritDoc} */
     public void sectionTitle2()
     {
         type = TYPE_SECTION_2;
     }
 
+    /** {@inheritDoc} */
     public void section2_()
     {
         pop();
     }
 
+    /** {@inheritDoc} */
     public void sectionTitle3()
     {
         type = TYPE_SECTION_3;
     }
 
+    /** {@inheritDoc} */
     public void section3_()
     {
         pop();
     }
 
+    /** {@inheritDoc} */
     public void sectionTitle4()
     {
         type = TYPE_SECTION_4;
     }
 
+    /** {@inheritDoc} */
     public void section4_()
     {
         pop();
     }
 
+    /** {@inheritDoc} */
     public void sectionTitle5()
     {
         type = TYPE_SECTION_5;
     }
 
+    /** {@inheritDoc} */
     public void section5_()
     {
         pop();
@@ -152,6 +175,7 @@
     //        type = TYPE_TABLE;
     //    }
 
+    /** {@inheritDoc} */
     public void text( String text )
     {
         IndexEntry entry;

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/EchoMacro.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/EchoMacro.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/EchoMacro.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/EchoMacro.java Wed Jul 25 13:12:56 2007
@@ -24,13 +24,17 @@
 import java.util.Iterator;
 
 /**
+ * A simple macro that prints out the key and value of some supplied parameters.
+ *
  * @plexus.component role-hint="echo"
  */
 public class EchoMacro
     extends AbstractMacro
 {
+    /** System-dependent EOL. */
     private static final String EOL = System.getProperty( "line.separator" );
 
+    /** {@inheritDoc} */
     public void execute( Sink sink, MacroRequest request )
     {
         sink.verbatim( true );

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/Macro.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/Macro.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/Macro.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/Macro.java Wed Jul 25 13:12:56 2007
@@ -22,13 +22,24 @@
 import org.apache.maven.doxia.sink.Sink;
 
 /**
+ * Base interface of a macro.
+ *
  * @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
  * @version $Id:Macro.java 348605 2005-11-24 12:02:44 +1100 (Thu, 24 Nov 2005) brett $
  */
 public interface Macro
 {
+    /** The Plexus lookup role. */
     String ROLE = Macro.class.getName();
 
+    /**
+     * Execute the current macro using the given MacroRequest,
+     * and emit events into the given sink.
+     *
+     * @param sink The sink to receive the events.
+     * @param request The corresponding MacroRequest.
+     * @throws MacroExecutionException if an error occurred during execution.
+     */
     void execute( Sink sink, MacroRequest request )
         throws MacroExecutionException;
 

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/MacroExecutionException.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/MacroExecutionException.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/MacroExecutionException.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/MacroExecutionException.java Wed Jul 25 13:12:56 2007
@@ -20,18 +20,34 @@
  */
 
 /**
- * Warp an exception that occurs during the execution of a Doxia macro.
+ * Wrap an exception that occurs during the execution of a Doxia macro.
  *
  * @author <a href="mailto:brett@apache.org">Brett Porter</a>
  */
 public class MacroExecutionException
     extends Exception
 {
+    /**
+     * Construct a new MacroExecutionException with the specified detail message.
+     *
+     * @param message The detailed message.
+     * This can later be retrieved by the Throwable.getMessage() method.
+     */
     public MacroExecutionException( String message )
     {
         super( message );
     }
 
+    /**
+     * Construct a new MacroExecutionException with the specified
+     * detail message and cause.
+     *
+     * @param message The detailed message.
+     * This can later be retrieved by the Throwable.getMessage() method.
+     * @param cause the cause. This can be retrieved later by the
+     * Throwable.getCause() method. (A null value is permitted, and indicates
+     * that the cause is nonexistent or unknown.)
+     */
     public MacroExecutionException( String message, Throwable cause )
     {
         super( message, cause );

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/MacroRequest.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/MacroRequest.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/MacroRequest.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/MacroRequest.java Wed Jul 25 13:12:56 2007
@@ -28,31 +28,61 @@
  */
 public class MacroRequest
 {
+    /** The current base directory. */
     private File basedir;
 
+    /** A map of parameters. */
     private Map parameters;
 
-    public MacroRequest( Map parameters, File basedir )
+    /**
+     * Constructor.
+     *
+     * @param param A map of parameters.
+     * @param base The current base directory.
+     */
+    public MacroRequest( Map param, File base )
     {
-        this.parameters = parameters;
-        this.basedir = basedir;
+        this.parameters = param;
+        this.basedir = base;
     }
 
+    /**
+     * Returns the current base directory.
+     *
+     * @return The base dir.
+     */
     public File getBasedir()
     {
         return basedir;
     }
 
-    public void setBasedir( File basedir )
+    /**
+     * Sets the current base directory.
+     *
+     * @param base The current base directory.
+     */
+    public void setBasedir( File base )
     {
-        this.basedir = basedir;
+        this.basedir = base;
     }
 
+    /**
+     * Returns the map of parameters.
+     *
+     * @return The map of parameters.
+     */
     public Map getParameters()
     {
         return parameters;
     }
 
+    /**
+     * Returns on object from the map of parameters
+     * that corresponds to the given key.
+     *
+     * @param key The key to lookup the object.
+     * @return The value object.
+     */
     public Object getParameter( String key )
     {
         return parameters.get( key );

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/SwfMacro.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/SwfMacro.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/SwfMacro.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/SwfMacro.java Wed Jul 25 13:12:56 2007
@@ -37,11 +37,10 @@
 public class SwfMacro
     extends AbstractMacro
 {
+    /** System-dependent EOL. */
     private static final String EOL = System.getProperty( "line.separator" );
 
-    /**
-     * @see org.apache.maven.doxia.macro.Macro#execute(org.apache.maven.doxia.sink.Sink, org.apache.maven.doxia.macro.MacroRequest)
-     */
+    /** {@inheritDoc} */
     public void execute( Sink sink, MacroRequest request )
         throws MacroExecutionException
     {

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/manager/DefaultMacroManager.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/manager/DefaultMacroManager.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/manager/DefaultMacroManager.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/manager/DefaultMacroManager.java Wed Jul 25 13:12:56 2007
@@ -34,6 +34,7 @@
     /** @plexus.requirement role="org.apache.maven.doxia.macro.Macro" */
     private Map macros;
 
+    /** {@inheritDoc} */
     public Macro getMacro( String id )
         throws MacroNotFoundException
     {

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/manager/MacroManager.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/manager/MacroManager.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/manager/MacroManager.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/manager/MacroManager.java Wed Jul 25 13:12:56 2007
@@ -22,13 +22,24 @@
 import org.apache.maven.doxia.macro.Macro;
 
 /**
+ * Handles MacroManager lookups.
+ *
  * @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
  * @version $Id:MacroManager.java 348605 2005-11-24 12:02:44 +1100 (Thu, 24 Nov 2005) brett $
  */
 public interface MacroManager
 {
+    /** The Plexus lookup role. */
     String ROLE = MacroManager.class.getName();
 
+    /**
+     * Returns the MacroManager that corresponds to the given id.
+     *
+     * @param id The identifier.
+     * @return The corresponding MacroManager.
+     * @throws MacroNotFoundException if no MacroManager could be found
+     * for the given id.
+     */
     Macro getMacro( String id )
         throws MacroNotFoundException;
 

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/manager/MacroNotFoundException.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/manager/MacroNotFoundException.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/manager/MacroNotFoundException.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/manager/MacroNotFoundException.java Wed Jul 25 13:12:56 2007
@@ -20,22 +20,49 @@
  */
 
 /**
+ * Encapsulate an exception that indicates that a Macro
+ * does not exist or could not be found.
+ *
  * @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
  * @version $Id:MacroNotFoundException.java 348605 2005-11-24 12:02:44 +1100 (Thu, 24 Nov 2005) brett $
  */
 public class MacroNotFoundException
     extends Exception
 {
+    /**
+     * Construct a new MacroNotFoundException with the specified detail message.
+     *
+     * @param message The detailed message.
+     * This can later be retrieved by the Throwable.getMessage() method.
+     */
     public MacroNotFoundException( String message )
     {
         super( message );
     }
 
+    /**
+     * Constructs a new MacroNotFoundException with the specified cause
+     * and a detail message of (cause == null ? null : cause.toString() ).
+     *
+     * @param cause the cause. This can be retrieved later by the
+     * Throwable.getCause() method. (A null value is permitted, and indicates
+     * that the cause is nonexistent or unknown.)
+     */
     public MacroNotFoundException( Throwable cause )
     {
         super( cause );
     }
 
+    /**
+     * Construct a new MacroNotFoundException with the specified
+     * detail message and cause.
+     *
+     * @param message The detailed message.
+     * This can later be retrieved by the Throwable.getMessage() method.
+     * @param cause the cause. This can be retrieved later by the
+     * Throwable.getCause() method. (A null value is permitted, and indicates
+     * that the cause is nonexistent or unknown.)
+     */
     public MacroNotFoundException( String message, Throwable cause )
     {
         super( message, cause );

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/snippet/SnippetMacro.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/snippet/SnippetMacro.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/snippet/SnippetMacro.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/snippet/SnippetMacro.java Wed Jul 25 13:12:56 2007
@@ -33,21 +33,29 @@
 import java.util.Map;
 
 /**
+ * A macro that prints out the content of a file or a URL.
+ *
  * @plexus.component role-hint="snippet"
  */
 public class SnippetMacro
     extends AbstractMacro
 {
+    /** System-dependent EOL. */
     static final String EOL = System.getProperty( "line.separator" );
 
+    /** Holds the cache. */
     private Map cache = new HashMap();
 
-    private long timeout = 60 * 60 * 1000; // one hour default cache
+    /** One hour default cache. */
+    private long timeout = 60 * 60 * 1000;
 
+    /** Holds the time cache. */
     private Map timeCached = new HashMap();
 
+    /** Debug. */
     private boolean debug = false;
 
+    /** {@inheritDoc} */
     public void execute( Sink sink, MacroRequest request )
         throws MacroExecutionException
     {
@@ -113,6 +121,14 @@
         sink.verbatim_();
     }
 
+    /**
+     * Return a snippet of the given url.
+     *
+     * @param url The URL to parse.
+     * @param id The id of the snippet.
+     * @return The snippet.
+     * @throws IOException if something goes wrong.
+     */
     private StringBuffer getSnippet( URL url, String id )
         throws IOException
     {
@@ -144,6 +160,13 @@
         return result;
     }
 
+    /**
+     * Return a snippet from the cache.
+     *
+     * @param url The URL to parse.
+     * @param id The id of the snippet.
+     * @return The snippet.
+     */
     private Object getCachedSnippet( URL url, String id )
     {
         if ( isCacheTimedout( url, id ) )
@@ -153,16 +176,38 @@
         return cache.get( globalSnippetId( url, id ) );
     }
 
+    /**
+     * Return true if the snippet has been cached longer than
+     * the current timeout.
+     *
+     * @param url The URL to parse.
+     * @param id The id of the snippet.
+     * @return True if timeout exceeded.
+     */
     boolean isCacheTimedout( URL url, String id )
     {
         return timeInCache( url, id ) >= timeout;
     }
 
+    /**
+     * Return the time the snippet has been cached.
+     *
+     * @param url The URL to parse.
+     * @param id The id of the snippet.
+     * @return The cache time.
+     */
     long timeInCache( URL url, String id )
     {
         return System.currentTimeMillis() - getTimeCached( url, id );
     }
 
+    /**
+     * Return the absolute value of when the snippet has been cached.
+     *
+     * @param url The URL to parse.
+     * @param id The id of the snippet.
+     * @return The cache time.
+     */
     long getTimeCached( URL url, String id )
     {
         String globalId = globalSnippetId( url, id );
@@ -170,6 +215,12 @@
         return timeCached.containsKey( globalId ) ? ( (Long) timeCached.get( globalId ) ).longValue() : 0;
     }
 
+    /**
+     * Removes the snippet from the cache.
+     *
+     * @param url The URL to parse.
+     * @param id The id of the snippet.
+     */
     private void removeFromCache( URL url, String id )
     {
         String globalId = globalSnippetId( url, id );
@@ -179,11 +230,25 @@
         cache.remove( globalId );
     }
 
+    /**
+     * Return a global identifier for the snippet.
+     *
+     * @param url The URL to parse.
+     * @param id The id of the snippet.
+     * @return An identifier, concatenated url and id.
+     */
     private String globalSnippetId( URL url, String id )
     {
         return url + " " + id;
     }
 
+    /**
+     * Check if the given parameter is required. Throws an
+     * IllegalArgumentException if id is null or empty.
+     *
+     * @param id The id of the snippet.
+     * @param param The parameter to check.
+     */
     private void required( String id, String param )
     {
         if ( id == null || "".equals( id ) )
@@ -192,6 +257,13 @@
         }
     }
 
+    /**
+     *Puts the given snippet into the cache.
+     *
+     * @param url The URL to parse.
+     * @param id The id of the snippet.
+     * @param content The content of the snippet.
+     */
     public void cacheSnippet( URL url, String id, String content )
     {
         cache.put( globalSnippetId( url, id ), content );
@@ -199,8 +271,13 @@
         timeCached.put( globalSnippetId( url, id ), new Long( System.currentTimeMillis() ) );
     }
 
-    public void setCacheTimeout( int timeout )
+    /**
+     * Set the cache timeout.
+     *
+     * @param time The timeout to set.
+     */
+    public void setCacheTimeout( int time )
     {
-        this.timeout = timeout;
+        this.timeout = time;
     }
 }

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/snippet/SnippetReader.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/snippet/SnippetReader.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/snippet/SnippetReader.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/snippet/SnippetReader.java Wed Jul 25 13:12:56 2007
@@ -27,17 +27,32 @@
 import java.util.Iterator;
 import java.util.List;
 
+/** Utility class for reading snippets. */
 public class SnippetReader
 {
+    /** System-dependent EOL. */
     private static final String EOL = System.getProperty( "line.separator" );
 
+    /** The source. */
     private URL source;
 
-    public SnippetReader( URL source )
-    {
-        this.source = source;
-    }
-
+    /**
+     * Constructor.
+     *
+     * @param src The source.
+     */
+    public SnippetReader( URL src )
+    {
+        this.source = src;
+    }
+
+    /**
+     * Reads the snippet with given id.
+     *
+     * @param snippetId The id of the snippet.
+     * @return The snippet.
+     * @throws IOException if something goes wrong.
+     */
     public StringBuffer readSnippet( String snippetId )
         throws IOException
     {
@@ -53,6 +68,12 @@
         return result;
     }
 
+    /**
+     * Returns the minimal indent of all the lines in the given List.
+     *
+     * @param lines A List of lines.
+     * @return the minimal indent.
+     */
     int minIndent( List lines )
     {
         int minIndent = Integer.MAX_VALUE;
@@ -64,6 +85,12 @@
         return minIndent;
     }
 
+    /**
+     * Returns the indent of the given line.
+     *
+     * @param line A line.
+     * @return the indent.
+     */
     int indent( String line )
     {
         char[] chars = line.toCharArray();
@@ -78,6 +105,13 @@
         return indent;
     }
 
+    /**
+     * Reads the snippet and returns the lines in a List.
+     *
+     * @param snippetId The id of the snippet.
+     * @return A List of lines.
+     * @throws IOException if something goes wrong.
+     */
     private List readLines( String snippetId )
         throws IOException
     {
@@ -110,18 +144,41 @@
         return lines;
     }
 
+    /**
+     * Determines if the given line is a start demarcator.
+     *
+     * @param snippetId the id of the snippet.
+     * @param line the line.
+     * @return True, if the line is a start demarcator.
+     */
     protected boolean isStart( String snippetId, String line )
     {
         return isDemarcator( snippetId, "START", line );
     }
 
+    /**
+     * Determines if the given line is a demarcator.
+     *
+     * @param snippetId the id of the snippet.
+     * @param what Identifier for the demarcator.
+     * @param line the line.
+     * @return True, if the line is a start demarcator.
+     */
     protected boolean isDemarcator( String snippetId, String what, String line )
     {
         String upper = line.toUpperCase();
-        return upper.indexOf( what.toUpperCase() ) != -1 && upper.indexOf( "SNIPPET" ) != -1 &&
-            line.indexOf( snippetId ) != -1;
+        return upper.indexOf( what.toUpperCase() ) != -1
+            && upper.indexOf( "SNIPPET" ) != -1
+            && line.indexOf( snippetId ) != -1;
     }
 
+    /**
+     * Determines if the given line is an end demarcator.
+     *
+     * @param snippetId the id of the snippet.
+     * @param line the line.
+     * @return True, if the line is an end demarcator.
+     */
     protected boolean isEnd( String snippetId, String line )
     {
         return isDemarcator( snippetId, "END", line );

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/toc/TocMacro.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/toc/TocMacro.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/toc/TocMacro.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/macro/toc/TocMacro.java Wed Jul 25 13:12:56 2007
@@ -34,10 +34,12 @@
 import org.codehaus.plexus.util.StringUtils;
 
 /**
- * Macro to display a <code>Table Of Content</code> in a given <code>Sink</code>. The input for this macro are:
+ * Macro to display a <code>Table Of Content</code> in a given <code>Sink</code>.
+ * The input for this macro are:
  * <dl>
  * <dt>section</dt>
- * <dd>Display the specificated section number or all sections if 0 (in this case, other paramaters are ignored).<br/>
+ * <dd>Display the specificated section number or all sections if 0
+ * (in this case, other paramaters are ignored).<br/>
  * Positive int, not mandatory, 0 by default.</dd>
  * <dt>fromDepth</dt>
  * <dd>Display the depth starting for the given section number.<br/>
@@ -49,11 +51,14 @@
  * For instance, in an APT file, you could write:
  * <dl>
  * <dt>%{toc|section=2|fromDepth=2|toDepth=2}</dt>
- * <dd>Display a TOC for the section number 2 in the document, from the subsection depth 1 to the subsection depth 2</dd>
+ * <dd>Display a TOC for the section number 2 in the document, from the
+ * subsection depth 1 to the subsection depth 2</dd>
  * <dt>%{toc}</dt>
- * <dd>display a TOC with all section and subsections (similar to %{toc|section=0} )</dd>
+ * <dd>display a TOC with all section and subsections
+ * (similar to %{toc|section=0} )</dd>
  * </dl>
- * Moreover, you need to write APT link for section to allow anchor, for instance:
+ * Moreover, you need to write APT link for section to allow anchor,
+ * for instance:
  * <pre>
  * * {SubSection 1}
  * </pre>
@@ -71,15 +76,19 @@
 public class TocMacro
     extends AbstractMacro
 {
+    /** The section to display. */
     private int section;
 
+    /** Start depth. */
     private int fromDepth;
 
+    /** End depth. */
     private int toDepth;
 
-    /**
-     * @see org.apache.maven.doxia.macro.Macro#execute(org.apache.maven.doxia.sink.Sink, org.apache.maven.doxia.macro.MacroRequest)
-     */
+    /** The default end depth. */
+    private static final int DEFAULT_DEPTH = 5;
+
+    /** {@inheritDoc} */
     public void execute( Sink sink, MacroRequest request )
         throws MacroExecutionException
     {
@@ -90,12 +99,12 @@
         if ( section != 0 )
         {
             fromDepth = getInt( request, "fromDepth", 0 );
-            toDepth = getInt( request, "toDepth", 5 );
+            toDepth = getInt( request, "toDepth", DEFAULT_DEPTH );
         }
         else
         {
             fromDepth = 0;
-            toDepth = 5;
+            toDepth = DEFAULT_DEPTH;
         }
         IndexEntry index = new IndexEntry( "index" );
         IndexingSink tocSink = new IndexingSink( index );
@@ -133,9 +142,9 @@
     }
 
     /**
-     * @param sink
-     * @param sectionIndex
-     * @param n
+     * @param sink The sink to write to.
+     * @param sectionIndex The section index.
+     * @param n The toc depth.
      */
     private void writeSubSectionN( Sink sink, IndexEntry sectionIndex, int n )
     {
@@ -158,7 +167,7 @@
                 for ( Iterator it = sectionIndex.getChildEntries().iterator(); it.hasNext(); )
                 {
                     IndexEntry subsectionIndex = (IndexEntry) it.next();
-                    if ( n == 5 )
+                    if ( n == DEFAULT_DEPTH )
                     {
                         sink.listItem();
                         sink.link( "#" + HtmlTools.encodeId( subsectionIndex.getId() ) );
@@ -185,11 +194,11 @@
     }
 
     /**
-     * @param request
-     * @param parameter
-     * @param defaultValue
-     * @return the int value of an parameter in the request.
-     * @throws MacroExecutionException
+     * @param request The MacroRequest.
+     * @param parameter The parameter.
+     * @param defaultValue the default value.
+     * @return the int value of a parameter in the request.
+     * @throws MacroExecutionException if something goes wrong.
      */
     private static int getInt( MacroRequest request, String parameter, int defaultValue )
         throws MacroExecutionException

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java Wed Jul 25 13:12:56 2007
@@ -29,6 +29,9 @@
 import org.apache.maven.doxia.sink.Sink;
 
 /**
+ * An abstract base class that defines some convenience methods for parsers.
+ * Provides a macro mechanism to give dynamic functionalities for the parsing.
+ *
  * @author Jason van Zyl
  * @version $Id:AbstractParser.java 348605 2005-11-24 12:02:44 +1100 (Thu, 24 Nov 2005) brett $
  * @plexus.component
@@ -36,11 +39,21 @@
 public abstract class AbstractParser
     implements Parser
 {
+    /** Indicates that a second parsing is required. */
     protected boolean secondParsing = false;
 
     /** @plexus.requirement */
     protected MacroManager macroManager;
 
+    /**
+     * 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 MacroExecutionException if an error occurred during execution.
+     * @throws 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.
     public void executeMacro( String macroId,
@@ -53,6 +66,11 @@
         macro.execute( sink, request );
     }
 
+    /**
+     * Returns the current base directory.
+     *
+     * @return The base directory.
+     */
     protected File getBasedir()
     {
         // TODO: This is baaad, it should come in with the request.
@@ -68,12 +86,12 @@
     }
 
     /**
-     * Set <code>secondParsing</code> to true, if we need a second parsing
+     * Set <code>secondParsing</code> to true, if we need a second parsing.
      *
-     * @param secondParsing
+     * @param second True for second parsing.
      */
-    public void setSecondParsing( boolean secondParsing )
+    public void setSecondParsing( boolean second )
     {
-        this.secondParsing = secondParsing;
+        this.secondParsing = second;
     }
 }

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/ParseException.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/ParseException.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/ParseException.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/ParseException.java Wed Jul 25 13:12:56 2007
@@ -20,49 +20,116 @@
  */
 
 /**
+ * Encapsulate a Doxia parse error.
+ *
  * @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
  * @version $Id:ParseException.java 348605 2005-11-24 12:02:44 +1100 (Thu, 24 Nov 2005) brett $
  */
 public class ParseException
     extends Exception
 {
+    /** 
+     * The file that caused the ParseException..
+     *
+     * @todo Make private.
+     */
     protected String fileName;
 
+    /** 
+     * Line number where the parse exception occurred.
+     *
+     * @todo Make private.
+     */
     protected int lineNumber;
 
+    /**
+     * Construct a new ParseException with the specified detail message.
+     *
+     * @param message The detailed message.
+     * This can later be retrieved by the Throwable.getMessage() method.
+     */
     public ParseException( String message )
     {
         this( null, message, null, -1 );
     }
 
+    /**
+     * Construct a new ParseException with the specified detail message and cause.
+     *
+     * @param message The detailed message.
+     * This can later be retrieved by the Throwable.getMessage() method.
+     * @param e the cause. This can be retrieved later by the Throwable.getCause() method.
+     * (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
+     */
     public ParseException( String message, Exception e )
     {
         this( e, message, null, -1 );
     }
 
+    /**
+     * Constructs a new exception with the specified cause and a detail message of
+     *  (cause == null ? null : cause.toString() ).
+     *
+     * @param e the cause. This can be retrieved later by the Throwable.getCause() method.
+     * (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
+     */
     public ParseException( Exception e )
     {
         this( e, null, null, -1 );
     }
 
-    public ParseException( Exception e, String fileName, int lineNumber )
-    {
-        this( e, null, fileName, lineNumber );
-    }
-
-    public ParseException( Exception e, String message, String fileName, int lineNumber )
+    /**
+     * Construct a new ParseException with the specified cause,
+     * filename and linenumber.
+     *
+     * @param e the cause. This can be retrieved later by the Throwable.getCause() method.
+     * (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
+     * @param file Name of a file that couldn't be parsed.
+     * This can later be retrieved by the getFileName() method.
+     * @param line The line number where the parsing failed.
+     * This can later be retrieved by the getLineNumber() method.
+     */
+    public ParseException( Exception e, String file, int line )
+    {
+        this( e, null, file, line );
+    }
+
+    /**
+     * Construct a new ParseException with the specified cause, detail message,
+     * filename and linenumber.
+     *
+     * @param e the cause. This can be retrieved later by the Throwable.getCause() method.
+     * (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
+     * @param message The detailed message.
+     * This can later be retrieved by the Throwable.getMessage() method.
+     * @param file Name of a file that couldn't be parsed.
+     * This can later be retrieved by the getFileName() method.
+     * @param line The line number where the parsing failed.
+     * This can later be retrieved by the getLineNumber() method.
+     */
+    public ParseException( Exception e, String message, String file, int line )
     {
         super( ( message == null ) ? ( ( e == null ) ? null : e.getMessage() ) : message, e );
 
-        this.fileName = fileName;
-        this.lineNumber = lineNumber;
+        this.fileName = file;
+        this.lineNumber = line;
     }
 
+    /** 
+     * Returns the file that caused the ParseException.
+     *
+     * @return the file that caused the ParseException.
+     */
     public String getFileName()
     {
         return fileName;
     }
 
+    /** 
+     * Returns the line number where the  ParseException ocurred.
+     *
+     * @return the line number.
+     */
     public int getLineNumber()
     {
         return lineNumber;

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/Parser.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/Parser.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/Parser.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/Parser.java Wed Jul 25 13:12:56 2007
@@ -24,19 +24,34 @@
 import java.io.Reader;
 
 /**
+ * A Parser is responsible for parsing any document in a supported front-end
+ * format, and emitting the standard Doxia events, which can then be consumed
+ * by any Doxia Sink.
+ *
  * @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
  * @version $Id:Parser.java 348605 2005-11-24 12:02:44 +1100 (Thu, 24 Nov 2005) brett $
  */
 public interface Parser
 {
+    /** The Plexus lookup role. */
     String ROLE = Parser.class.getName();
 
+    /** Used for table cells: justify center. */
     int JUSTIFY_CENTER = 0;
 
+    /** Used for table cells: justify left. */
     int JUSTIFY_LEFT = 1;
 
+    /** Used for table cells: justify right. */
     int JUSTIFY_RIGHT = 2;
 
+    /**
+     * Parses the given source model and emits Doxia events into the given sink.
+     * 
+     * @param source A reader that provides the source document.
+     * @param sink A sink that consumes the Doxia events.
+     * @throws ParseException if the model could not be parsed.
+     */
     void parse( Reader source, Sink sink )
         throws ParseException;
 }

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/manager/DefaultParserManager.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/manager/DefaultParserManager.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/manager/DefaultParserManager.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/manager/DefaultParserManager.java Wed Jul 25 13:12:56 2007
@@ -24,6 +24,8 @@
 import java.util.Map;
 
 /**
+ * Simple implementation of the ParserManager interface.
+ *
  * @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
  * @version $Id:DefaultParserManager.java 348605 2005-11-24 12:02:44 +1100 (Thu, 24 Nov 2005) brett $
  * @plexus.component
@@ -36,6 +38,7 @@
      */
     private Map parsers;
 
+   /** {@inheritDoc} */
     public Parser getParser( String id )
         throws ParserNotFoundException
     {

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/manager/ParserManager.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/manager/ParserManager.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/manager/ParserManager.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/manager/ParserManager.java Wed Jul 25 13:12:56 2007
@@ -22,13 +22,24 @@
 import org.apache.maven.doxia.parser.Parser;
 
 /**
+ * Handles parser lookups.
+ *
  * @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
  * @version $Id:ParserManager.java 348605 2005-11-24 12:02:44 +1100 (Thu, 24 Nov 2005) brett $
  */
 public interface ParserManager
 {
+    /** The Plexus lookup role. */
     String ROLE = ParserManager.class.getName();
 
+    /**
+     * Returns the parser that corresponds to the given id.
+     *
+     * @param id The identifier.
+     * @return The corresponding parser.
+     * @throws ParserNotFoundException if no parser could be found
+     * for the given id.
+     */
     Parser getParser( String id )
         throws ParserNotFoundException;
 }

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/manager/ParserNotFoundException.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/manager/ParserNotFoundException.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/manager/ParserNotFoundException.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/parser/manager/ParserNotFoundException.java Wed Jul 25 13:12:56 2007
@@ -20,22 +20,49 @@
  */
 
 /**
+ * Encapsulate a Doxia exception that indicates that a parser
+ * does not exist or could not be found.
+ *
  * @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
  * @version $Id:ParserNotFoundException.java 348605 2005-11-24 12:02:44 +1100 (Thu, 24 Nov 2005) brett $
  */
 public class ParserNotFoundException
     extends Exception
 {
+    /**
+     * Construct a new ParserNotFoundException with the specified detail message.
+     *
+     * @param message The detailed message.
+     * This can later be retrieved by the Throwable.getMessage() method.
+     */
     public ParserNotFoundException( String message )
     {
         super( message );
     }
 
+    /**
+     * Constructs a new exception with the specified cause and a detail
+     * message of (cause == null ? null : cause.toString() ).
+     *
+     * @param cause the cause. This can be retrieved later by the
+     * Throwable.getCause() method. (A null value is permitted, and indicates
+     * that the cause is nonexistent or unknown.)
+     */
     public ParserNotFoundException( Throwable cause )
     {
         super( cause );
     }
 
+    /**
+     * Construct a new ParserNotFoundException with the specified
+     * detail message and cause.
+     *
+     * @param message The detailed message.
+     * This can later be retrieved by the Throwable.getMessage() method.
+     * @param cause the cause. This can be retrieved later by the
+     * Throwable.getCause() method. (A null value is permitted, and indicates
+     * that the cause is nonexistent or unknown.)
+     */
     public ParserNotFoundException( String message, Throwable cause )
     {
         super( message, cause );

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/sink/SinkAdapter.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/sink/SinkAdapter.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/sink/SinkAdapter.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/sink/SinkAdapter.java Wed Jul 25 13:12:56 2007
@@ -30,710 +30,535 @@
 public class SinkAdapter
     implements Sink
 {
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#head()
-     */
+    /** {@inheritDoc} */
     public void head()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#head_()
-     */
+    /** {@inheritDoc} */
     public void head_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#body()
-     */
+    /** {@inheritDoc} */
     public void body()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#body_()
-     */
+    /** {@inheritDoc} */
     public void body_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#section1()
-     */
+    /** {@inheritDoc} */
     public void section1()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#section1_()
-     */
+    /** {@inheritDoc} */
     public void section1_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#section2()
-     */
+    /** {@inheritDoc} */
     public void section2()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#section2_()
-     */
+    /** {@inheritDoc} */
     public void section2_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#section3()
-     */
+    /** {@inheritDoc} */
     public void section3()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#section3_()
-     */
+    /** {@inheritDoc} */
     public void section3_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#section4()
-     */
+    /** {@inheritDoc} */
     public void section4()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#section4_()
-     */
+    /** {@inheritDoc} */
     public void section4_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#section5()
-     */
+    /** {@inheritDoc} */
     public void section5()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#section5_()
-     */
+    /** {@inheritDoc} */
     public void section5_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#list()
-     */
+    /** {@inheritDoc} */
     public void list()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#list_()
-     */
+    /** {@inheritDoc} */
     public void list_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#listItem()
-     */
+    /** {@inheritDoc} */
     public void listItem()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#listItem_()
-     */
+    /** {@inheritDoc} */
     public void listItem_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#numberedList(int)
-     */
+    /** {@inheritDoc} */
     public void numberedList( int numbering )
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#numberedList_()
-     */
+    /** {@inheritDoc} */
     public void numberedList_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#numberedListItem()
-     */
+    /** {@inheritDoc} */
     public void numberedListItem()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#numberedListItem_()
-     */
+    /** {@inheritDoc} */
     public void numberedListItem_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#definitionList()
-     */
+    /** {@inheritDoc} */
     public void definitionList()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#definitionList_()
-     */
+    /** {@inheritDoc} */
     public void definitionList_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#definitionListItem()
-     */
+    /** {@inheritDoc} */
     public void definitionListItem()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#definitionListItem_()
-     */
+    /** {@inheritDoc} */
     public void definitionListItem_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#definition()
-     */
+    /** {@inheritDoc} */
     public void definition()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#definition_()
-     */
+    /** {@inheritDoc} */
     public void definition_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#figure()
-     */
+    /** {@inheritDoc} */
     public void figure()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#figure_()
-     */
+    /** {@inheritDoc} */
     public void figure_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#table()
-     */
+    /** {@inheritDoc} */
     public void table()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#table_()
-     */
+    /** {@inheritDoc} */
     public void table_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#tableRows(int[], boolean)
-     */
+    /** {@inheritDoc} */
     public void tableRows( int[] justification, boolean grid )
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#tableRows_()
-     */
+    /** {@inheritDoc} */
     public void tableRows_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#tableRow()
-     */
+    /** {@inheritDoc} */
     public void tableRow()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#tableRow_()
-     */
+    /** {@inheritDoc} */
     public void tableRow_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#title()
-     */
+    /** {@inheritDoc} */
     public void title()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#title_()
-     */
+    /** {@inheritDoc} */
     public void title_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#author()
-     */
+    /** {@inheritDoc} */
     public void author()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#author_()
-     */
+    /** {@inheritDoc} */
     public void author_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#date()
-     */
+    /** {@inheritDoc} */
     public void date()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#date_()
-     */
+    /** {@inheritDoc} */
     public void date_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#sectionTitle()
-     */
+    /** {@inheritDoc} */
     public void sectionTitle()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#sectionTitle_()
-     */
+    /** {@inheritDoc} */
     public void sectionTitle_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#sectionTitle1()
-     */
+    /** {@inheritDoc} */
     public void sectionTitle1()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#sectionTitle1_()
-     */
+    /** {@inheritDoc} */
     public void sectionTitle1_()
     {
         // nop
     }
 
+    /** {@inheritDoc} */
     public void sectionTitle2()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#sectionTitle2_()
-     */
+    /** {@inheritDoc} */
     public void sectionTitle2_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#sectionTitle3()
-     */
+    /** {@inheritDoc} */
     public void sectionTitle3()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#sectionTitle3_()
-     */
+    /** {@inheritDoc} */
     public void sectionTitle3_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#sectionTitle4()
-     */
+    /** {@inheritDoc} */
     public void sectionTitle4()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#sectionTitle4_()
-     */
+    /** {@inheritDoc} */
     public void sectionTitle4_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#sectionTitle5()
-     */
+    /** {@inheritDoc} */
     public void sectionTitle5()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#sectionTitle5_()
-     */
+    /** {@inheritDoc} */
     public void sectionTitle5_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#paragraph()
-     */
+    /** {@inheritDoc} */
     public void paragraph()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#paragraph_()
-     */
+    /** {@inheritDoc} */
     public void paragraph_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#verbatim(boolean)
-     */
+    /** {@inheritDoc} */
     public void verbatim( boolean boxed )
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#verbatim_()
-     */
+    /** {@inheritDoc} */
     public void verbatim_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#definedTerm()
-     */
+    /** {@inheritDoc} */
     public void definedTerm()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#definedTerm_()
-     */
+    /** {@inheritDoc} */
     public void definedTerm_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#figureCaption()
-     */
+    /** {@inheritDoc} */
     public void figureCaption()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#figureCaption_()
-     */
+    /** {@inheritDoc} */
     public void figureCaption_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#tableCell()
-     */
+    /** {@inheritDoc} */
     public void tableCell()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#tableCell(java.lang.String)
-     */
+    /** {@inheritDoc} */
     public void tableCell( String width )
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#tableCell_()
-     */
+    /** {@inheritDoc} */
     public void tableCell_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#tableHeaderCell()
-     */
+    /** {@inheritDoc} */
     public void tableHeaderCell()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#tableHeaderCell(java.lang.String)
-     */
+    /** {@inheritDoc} */
     public void tableHeaderCell( String width )
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#tableHeaderCell_()
-     */
+    /** {@inheritDoc} */
     public void tableHeaderCell_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#tableCaption()
-     */
+    /** {@inheritDoc} */
     public void tableCaption()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#tableCaption_()
-     */
+    /** {@inheritDoc} */
     public void tableCaption_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#figureGraphics(java.lang.String)
-     */
+    /** {@inheritDoc} */
     public void figureGraphics( String name )
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#horizontalRule()
-     */
+    /** {@inheritDoc} */
     public void horizontalRule()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#pageBreak()
-     */
+    /** {@inheritDoc} */
     public void pageBreak()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#anchor(java.lang.String)
-     */
+    /** {@inheritDoc} */
     public void anchor( String name )
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#anchor_()
-     */
+    /** {@inheritDoc} */
     public void anchor_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#link(java.lang.String)
-     */
+    /** {@inheritDoc} */
     public void link( String name )
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#link_()
-     */
+    /** {@inheritDoc} */
     public void link_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#italic()
-     */
+    /** {@inheritDoc} */
     public void italic()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#italic_()
-     */
+    /** {@inheritDoc} */
     public void italic_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#bold()
-     */
+    /** {@inheritDoc} */
     public void bold()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#bold_()
-     */
+    /** {@inheritDoc} */
     public void bold_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#monospaced()
-     */
+    /** {@inheritDoc} */
     public void monospaced()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#monospaced_()
-     */
+    /** {@inheritDoc} */
     public void monospaced_()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#lineBreak()
-     */
+    /** {@inheritDoc} */
     public void lineBreak()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#nonBreakingSpace()
-     */
+    /** {@inheritDoc} */
     public void nonBreakingSpace()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#text(java.lang.String)
-     */
+    /** {@inheritDoc} */
     public void text( String text )
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#rawText(java.lang.String)
-     */
+    /** {@inheritDoc} */
     public void rawText( String text )
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#flush()
-     */
+    /** {@inheritDoc} */
     public void flush()
     {
         // nop
     }
 
-    /**
-     * @see org.apache.maven.doxia.sink.Sink#close()
-     */
+    /** {@inheritDoc} */
     public void close()
     {
         // nop

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/sink/StructureSink.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/sink/StructureSink.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/sink/StructureSink.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/sink/StructureSink.java Wed Jul 25 13:12:56 2007
@@ -19,13 +19,13 @@
  * under the License.
  */
 
-import java.io.File;
-
+/** Utility methods for Sinks. */
 public class StructureSink
 {
     /**
      * Checks if the given string corresponds to an external URI,
      * ie is not a link within the same document. 
+     *
      * @param link The link to check.
      * @return True if the link (ignoring case) starts with either of the
      * following: "http:/", "https:/", "ftp:/", "mailto:", "file:/",
@@ -36,11 +36,19 @@
     {
         String text = link.toLowerCase();
 
-        return ( text.indexOf( "http:/" ) == 0 || text.indexOf( "https:/" ) == 0 || text.indexOf( "ftp:/" ) == 0 ||
-            text.indexOf( "mailto:" ) == 0 || text.indexOf( "file:/" ) == 0 ||
-            text.indexOf( "../" ) == 0 || text.indexOf( "./" ) == 0 );
+        return ( text.indexOf( "http:/" ) == 0 || text.indexOf( "https:/" ) == 0
+            || text.indexOf( "ftp:/" ) == 0 || text.indexOf( "mailto:" ) == 0
+            || text.indexOf( "file:/" ) == 0 || text.indexOf( "../" ) == 0
+            || text.indexOf( "./" ) == 0 );
     }
 
+    /**
+     * Transforms the given text such that it can be used as a link.
+     *
+     * @param text The text to transform.
+     * @return A text with escaped special characters.
+     * @todo This is apt specific, need to clarify general use.
+     */
     public static String linkToKey( String text )
     {
         int length = text.length();

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/AbstractSiteModule.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/AbstractSiteModule.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/AbstractSiteModule.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/AbstractSiteModule.java Wed Jul 25 13:12:56 2007
@@ -20,6 +20,8 @@
  */
 
 /**
+ * An abstract base class that implements the SiteModule interface.
+ *
  * @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
  * @version $Id:AbstractSiteModule.java 348605 2005-11-24 12:02:44 +1100 (Thu, 24 Nov 2005) brett $
  * @plexus.component
@@ -27,15 +29,19 @@
 public abstract class AbstractSiteModule
     implements SiteModule
 {
+    /** The source directory. */
     private String sourceDirectory;
 
+    /** The default file extension. */
     private String extension;
 
+    /** {@inheritDoc} */
     public String getSourceDirectory()
     {
         return sourceDirectory;
     }
 
+    /** {@inheritDoc} */
     public String getExtension()
     {
         return extension;

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/SiteModule.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/SiteModule.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/SiteModule.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/SiteModule.java Wed Jul 25 13:12:56 2007
@@ -20,16 +20,31 @@
  */
 
 /**
+ * Provides definitions for a Doxia module. This is used by the doxia site tools.
+ *
  * @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
  * @version $Id:SiteModule.java 348605 2005-11-24 12:02:44 +1100 (Thu, 24 Nov 2005) brett $
  */
 public interface SiteModule
 {
+    /** The Plexus lookup role. */
     String ROLE = SiteModule.class.getName();
 
+    /** Returns the directory that contains source files for a given module.
+     *
+     * @return The source directory.
+     */
     String getSourceDirectory();
 
+    /** Returns the default file extension for a given module.
+     *
+     * @return The default file extension.
+     */
     String getExtension();
 
+    /** Returns the parser id for a given module.
+     *
+     * @return The parser id.
+     */
     String getParserId();
 }

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/manager/DefaultSiteModuleManager.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/manager/DefaultSiteModuleManager.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/manager/DefaultSiteModuleManager.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/manager/DefaultSiteModuleManager.java Wed Jul 25 13:12:56 2007
@@ -25,6 +25,8 @@
 import java.util.Map;
 
 /**
+ * Simple implementation of the SiteModuleManager interface.
+ *
  * @author Jason van Zyl
  * @version $Id:DefaultSiteModuleManager.java 348605 2005-11-24 12:02:44 +1100 (Thu, 24 Nov 2005) brett $
  * @plexus.component
@@ -37,11 +39,13 @@
      */
     private Map siteModules;
 
+    /** {@inheritDoc} */
     public Collection getSiteModules()
     {
         return siteModules.values();
     }
 
+    /** {@inheritDoc} */
     public SiteModule getSiteModule( String id )
         throws SiteModuleNotFoundException
     {

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/manager/SiteModuleManager.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/manager/SiteModuleManager.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/manager/SiteModuleManager.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/manager/SiteModuleManager.java Wed Jul 25 13:12:56 2007
@@ -24,15 +24,31 @@
 import java.util.Collection;
 
 /**
+ * Handles SiteModule lookups.
+ *
  * @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
  * @version $Id:SiteModuleManager.java 348605 2005-11-24 12:02:44 +1100 (Thu, 24 Nov 2005) brett $
  */
 public interface SiteModuleManager
 {
+    /** The Plexus lookup role. */
     String ROLE = SiteModuleManager.class.getName();
 
+    /**
+     * Returns a collection of SiteModules.
+     *
+     * @return The SiteModules.
+     */
     Collection getSiteModules();
 
+    /**
+     * Returns the SiteModule that corresponds to the given id.
+     *
+     * @param id The identifier.
+     * @return The corresponding SiteModule.
+     * @throws SiteModuleNotFoundException if no SiteModule could be found
+     * for the given id.
+     */
     SiteModule getSiteModule( String id )
         throws SiteModuleNotFoundException;
 }

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/manager/SiteModuleNotFoundException.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/manager/SiteModuleNotFoundException.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/manager/SiteModuleNotFoundException.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/site/module/manager/SiteModuleNotFoundException.java Wed Jul 25 13:12:56 2007
@@ -20,22 +20,50 @@
  */
 
 /**
+ * Encapsulate a Doxia exception that indicates that a SiteModule
+ * does not exist or could not be found.
+ *
  * @author <a href="mailto:jason@maven.org">Jason van Zyl</a>
  * @version $Id:SiteModuleNotFoundException.java 348605 2005-11-24 12:02:44 +1100 (Thu, 24 Nov 2005) brett $
  */
 public class SiteModuleNotFoundException
     extends Exception
 {
+    /**
+     * Construct a new SiteModuleNotFoundException with the
+     * specified detail message.
+     *
+     * @param message The detailed message.
+     * This can later be retrieved by the Throwable.getMessage() method.
+     */
     public SiteModuleNotFoundException( String message )
     {
         super( message );
     }
 
+    /**
+     * Constructs a new SiteModuleNotFoundException with the specified cause
+     * and a detail message of (cause == null ? null : cause.toString() ).
+     *
+     * @param cause the cause. This can be retrieved later by the
+     * Throwable.getCause() method. (A null value is permitted, and indicates
+     * that the cause is nonexistent or unknown.)
+     */
     public SiteModuleNotFoundException( Throwable cause )
     {
         super( cause );
     }
 
+    /**
+     * Construct a new SiteModuleNotFoundException with the specified
+     * detail message and cause.
+     *
+     * @param message The detailed message.
+     * This can later be retrieved by the Throwable.getMessage() method.
+     * @param cause The cause. This can be retrieved later by the
+     * Throwable.getCause() method. (A null value is permitted, and indicates
+     * that the cause is nonexistent or unknown.)
+     */
     public SiteModuleNotFoundException( String message, Throwable cause )
     {
         super( message, cause );

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/ByLineReaderSource.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/ByLineReaderSource.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/ByLineReaderSource.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/ByLineReaderSource.java Wed Jul 25 13:12:56 2007
@@ -1,7 +1,3 @@
-/*
- * Originaly from org.apache.doxia.module.apt.AptReaderSource. It was modified
- * to get unget support 
- */
 package org.apache.maven.doxia.util;
 
 /*
@@ -23,6 +19,11 @@
  * under the License.
  */
 
+/*
+ * Originally from org.apache.doxia.module.apt.AptReaderSource. It was modified
+ * to get unget support 
+ */
+
 import java.io.IOException;
 import java.io.LineNumberReader;
 import java.io.Reader;
@@ -38,6 +39,7 @@
      * reader
      */
     private LineNumberReader reader;
+
     /**
      * current line number
      */
@@ -66,9 +68,7 @@
         lineNumber = -1;
     }
 
-    /**
-     * @see ByLineSource#getNextLine()
-     */
+    /** {@inheritDoc} */
     public final String getNextLine() throws ParseException
     {
         if ( reader == null )
@@ -107,25 +107,19 @@
         return line;
     }
 
-    /**
-     * @see ByLineSource#getName()
-     */
+    /** {@inheritDoc} */
     public final String getName()
     {
         return "";
     }
 
-    /**
-     * @see ByLineSource#getLineNumber()
-     */
+    /** {@inheritDoc} */
     public final int getLineNumber()
     {
         return lineNumber;
     }
 
-    /**
-     * @see ByLineSource#close()
-     */
+    /** {@inheritDoc} */
     public final void close()
     {
         if ( reader != null )
@@ -142,9 +136,7 @@
         reader = null;
     }
 
-    /**
-     * @see ByLineSource#ungetLine()
-     */
+    /** {@inheritDoc} */
     public final void ungetLine() throws IllegalStateException
     {
         if ( ungetted )
@@ -154,9 +146,7 @@
         ungetted = true;
     }
 
-    /**
-     * @see ByLineSource#unget(String)
-     */
+    /** {@inheritDoc} */
     public final void unget( final String s ) throws IllegalStateException
     {
         if ( s == null )

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/FileUtil.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/FileUtil.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/FileUtil.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/FileUtil.java Wed Jul 25 13:12:56 2007
@@ -23,7 +23,6 @@
 import java.io.ByteArrayOutputStream;
 import java.io.File;
 import java.io.FileInputStream;
-import java.io.FileNotFoundException;
 import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
@@ -369,6 +368,8 @@
 
     /**
      * A simple test for all functions dealing with file path names.
+     *
+     * @param args An array of file path names to test.
      */
     public static void main( String[] args )
     {
@@ -505,7 +506,7 @@
      * @throws IOException if there is an IO problem
      */
     public static String loadString( String fileName )
-        throws FileNotFoundException, IOException
+        throws IOException
     {
         return loadString( new FileInputStream( fileName ) );
     }
@@ -740,6 +741,7 @@
 
     // -----------------------------------------------------------------------
 
+    /** The default character encoding for this platform. */
     private static String platformDefaultEncoding;
 
     static

Modified: maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/LineBreaker.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/LineBreaker.java?view=diff&rev=559578&r1=559577&r2=559578
==============================================================================
--- maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/LineBreaker.java (original)
+++ maven/doxia/doxia/trunk/doxia-core/src/main/java/org/apache/maven/doxia/util/LineBreaker.java Wed Jul 25 13:12:56 2007
@@ -25,50 +25,86 @@
 import java.io.IOException;
 import java.io.Writer;
 
+/** Allows to specify the line-length of an output writer. */
 public class LineBreaker
 {
+    /** The default maximal line length. */
     public static final int DEFAULT_MAX_LINE_LENGTH = 78;
 
+    /** The system dependent EOL. */
     private static final String EOL = System.getProperty( "line.separator" );
 
+    /** The destination writer. */
     private Writer destination;
 
+    /** The writer to use. */
     private BufferedWriter writer;
 
+    /** The maximal line length. */
     private int maxLineLength;
 
+    /** The current line length. */
     private int lineLength = 0;
 
+    /** The string buffer to store the current text. */
     private StringBuffer word = new StringBuffer( 1024 );
 
+    /**
+     * Constructs a new LineBreaker with DEFAULT_MAX_LINE_LENGTH.
+     *
+     * @param out The writer to use.
+     */
     public LineBreaker( Writer out )
     {
         this( out, DEFAULT_MAX_LINE_LENGTH );
     }
 
-    public LineBreaker( Writer out, int maxLineLength )
+    /**
+     * Constructs a new LineBreaker with the given max line length.
+     *
+     * @param out The writer to use.
+     * @param max The maximal line length.
+     */
+    public LineBreaker( Writer out, int max )
     {
-        if ( maxLineLength <= 0 )
+        if ( max <= 0 )
         {
-            throw new IllegalArgumentException( "maxLineLength<=0" );
+            throw new IllegalArgumentException( "maxLineLength <= 0" );
         }
 
         destination = out;
-        this.maxLineLength = maxLineLength;
+        this.maxLineLength = max;
         writer = new BufferedWriter( out );
     }
 
+    /**
+     * Returns the current destination writer.
+     *
+     * @return The destination.
+     */
     public Writer getDestination()
     {
         return destination;
     }
 
+    /**
+     * Writes the given text to the writer. White space is not preserved.
+     *
+     * @param text The text to write.
+     * @throws IOException if there's a problem writing the text.
+     */
     public void write( String text )
         throws IOException
     {
         write( text, /*preserveSpace*/ false );
     }
 
+    /**
+     * Writes the given text to the writer.
+     *
+     * @param text The text to write.
+     * @param preserveSpace True to preserve white space.
+     */
     public void write( String text, boolean preserveSpace )
     {
         int length = text.length();
@@ -105,10 +141,14 @@
         }
         catch ( Exception e )
         {
-
+            // TODO: log
         }
     }
 
+    /**
+     * Write out the current StringBuffer and flush the writer.
+     * Any IOException will be swallowed.
+     */
     public void flush()
     {
         try
@@ -118,9 +158,15 @@
         }
         catch ( IOException e )
         {
+            // TODO: log
         }
     }
 
+    /**
+     * Writes the current StringBuffer to the writer.
+     *
+     * @throws IOException if an exception occurs during writing.
+     */
     private void writeWord()
         throws IOException
     {
@@ -148,6 +194,7 @@
         }
     }
 
+    /** Close the writer. */
     public void close()
     {
         IOUtil.close( writer );



Mime
View raw message