You are viewing a plain text version of this content. The canonical link for it is here.
Posted to doxia-commits@maven.apache.org by lt...@apache.org on 2007/07/25 22:12:57 UTC
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/
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 );