Javadocs

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@651538 13f79535-47bb-0310-9956-ffa450edef68

3 files changed, 76 insertions, 3 deletions

diff --git a/src/codegen/java/org/apache/fop/tools/EventConventionException.java b/src/codegen/java/org/apache/fop/tools/EventConventionException.java
index 675f4a0ca..27a7fcd50 100644
--- a/src/codegen/java/org/apache/fop/tools/EventConventionException.java
+++ b/src/codegen/java/org/apache/fop/tools/EventConventionException.java
@@ -19,8 +19,17 @@
 
 package org.apache.fop.tools;
 
+/**
+ * This exception is used to indicate a violation of the conventions for event producers.
+ */
 public class EventConventionException extends Exception {
 
+    private static final long serialVersionUID = 117244726033986628L;
+
+    /**
+     * Creates a new EventConventionException
+     * @param message the error message
+     */
     public EventConventionException(String message) {
         super(message);
     }
diff --git a/src/codegen/java/org/apache/fop/tools/EventProducerCollector.java b/src/codegen/java/org/apache/fop/tools/EventProducerCollector.java
index e42395ae7..f7e320ee7 100644
--- a/src/codegen/java/org/apache/fop/tools/EventProducerCollector.java
+++ b/src/codegen/java/org/apache/fop/tools/EventProducerCollector.java
@@ -63,15 +63,29 @@ public class EventProducerCollector {
     private DocletTagFactory tagFactory;
     private EventModel model = new EventModel();
 
+    /**
+     * Creates a new EventProducerCollector.
+     */
     public EventProducerCollector() {
         this.tagFactory = createDocletTagFactory();
     }
 
+    /**
+     * Creates the {@link DocletTagFactory} to be used by the collector.
+     * @return the doclet tag factory
+     */
     protected DocletTagFactory createDocletTagFactory() {
         return new DefaultDocletTagFactory();
     }
 
-    public void scanFile(File src, String filename)
+    /**
+     * Scans a file and processes it if it extends the {@link EventProducer} interface.
+     * @param src the source file (a Java source file)
+     * @throws IOException if an I/O error occurs
+     * @throws EventConventionException if the EventProducer conventions are violated
+     * @throws ClassNotFoundException if a required class cannot be found
+     */
+    public void scanFile(File src)
             throws IOException, EventConventionException, ClassNotFoundException {
         JavaDocBuilder builder = new JavaDocBuilder(this.tagFactory);
         builder.addSource(src);
@@ -79,7 +93,7 @@ public class EventProducerCollector {
         for (int i = 0, c = classes.length; i < c; i++) {
             JavaClass clazz = classes[i];
             if (clazz.isInterface() && implementsInterface(clazz, CLASSNAME_EVENT_PRODUCER)) {
-                processEventProducerInterface(clazz, filename);
+                processEventProducerInterface(clazz, src.getName());
             }
         }
     }
@@ -172,10 +186,19 @@ public class EventProducerCollector {
         return methodMeta;
     }
 
+    /**
+     * Returns the event model that has been accumulated.
+     * @return the event model.
+     */
     public EventModel getModel() {
         return this.model;
     }
     
+    /**
+     * Saves the accumulated event model to an XML file.
+     * @param modelFile the target model file
+     * @throws IOException if an I/O error occurs
+     */
     public void saveModelToXML(File modelFile) throws IOException {
         getModel().saveToXML(modelFile);
     }
diff --git a/src/codegen/java/org/apache/fop/tools/EventProducerCollectorTask.java b/src/codegen/java/org/apache/fop/tools/EventProducerCollectorTask.java
index 755e3da0b..60ffaf103 100644
--- a/src/codegen/java/org/apache/fop/tools/EventProducerCollectorTask.java
+++ b/src/codegen/java/org/apache/fop/tools/EventProducerCollectorTask.java
@@ -45,6 +45,12 @@ import org.apache.tools.ant.Task;
 import org.apache.tools.ant.types.FileSet;
 import org.apache.tools.ant.types.selectors.FilenameSelector;
 
+/**
+ * Ant task which inspects a file set for Java interfaces which extend the
+ * {@link org.apache.fop.events.EventProducer} interface. For all such interfaces an event model
+ * file and a translation file for the human-readable messages generated by the events is
+ * created and/or updated.
+ */
 public class EventProducerCollectorTask extends Task {
 
     private List filesets = new java.util.ArrayList();
@@ -74,6 +80,10 @@ public class EventProducerCollectorTask extends Task {
     private static final String MODEL2TRANSLATION = "model2translation.xsl";
     private static final String MERGETRANSLATION = "merge-translation.xsl";
     
+    /**
+     * Updates the translation file with new entries for newly found event producer methods.
+     * @throws IOException if an I/O error occurs
+     */
     protected void updateTranslationFile() throws IOException {
         try {
             boolean resultExists = getTranslationFile().exists();
@@ -136,6 +146,13 @@ public class EventProducerCollectorTask extends Task {
         }
     }
 
+    /**
+     * Processes the file sets defined for the task.
+     * @param collector the collector to use for collecting the event producers
+     * @throws IOException if an I/O error occurs
+     * @throws EventConventionException if the EventProducer conventions are violated
+     * @throws ClassNotFoundException if a required class cannot be found
+     */
     protected void processFileSets(EventProducerCollector collector)
             throws IOException, EventConventionException, ClassNotFoundException {
         Iterator iter = filesets.iterator();
@@ -147,31 +164,55 @@ public class EventProducerCollectorTask extends Task {
             for (int i = 0, c = srcFiles.length; i < c; i++) {
                 String filename = srcFiles[i];
                 File src = new File(directory, filename);
-                collector.scanFile(src, filename);
+                collector.scanFile(src);
             }
         }
     }
 
+    /**
+     * Adds a file set.
+     * @param set the file set
+     */
     public void addFileset(FileSet set) {
         filesets.add(set);
     }
     
+    /**
+     * Sets the model file to be written.
+     * @param f the model file
+     */
     public void setModelFile(File f) {
         this.modelFile = f;
     }
     
+    /**
+     * Returns the model file to be written.
+     * @return the model file
+     */
     public File getModelFile() {
         return this.modelFile;
     }
     
+    /**
+     * Sets the translation file for the event producer methods.
+     * @param f the translation file
+     */
     public void setTranslationFile(File f) {
         this.translationFile = f;
     }
     
+    /**
+     * Returns the translation file for the event producer methods.
+     * @return the translation file
+     */
     public File getTranslationFile() {
         return this.translationFile;
     }
     
+    /**
+     * Command-line interface for testing purposes.
+     * @param args the command-line arguments
+     */
     public static void main(String[] args) {
         try {
             Project project = new Project();