Corrected javadocs in o.a.f.apps.* classes

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

src/java/org/apache/fop/apps/FOUserAgent.java

@@ -166,7 +166,7 @@ public class FOUserAgent {
      * requires an output stream and you want to configure this very rendering run,
      * i.e. if you want to set some metadata like the title and author of the document
      * you want to render. In that case, create a new {@link FOUserAgent} instance
-     * using {@link #newFOUserAgent()}.
+     * using {@link org.apache.fop.apps.FopFactory#newFOUserAgent() newFOUserAgent()}.
      * <p>
      * MIME types are used to select the output format (ex. "application/pdf" for PDF). You can
      * use the constants defined in {@link MimeConstants}.
@@ -184,7 +184,7 @@ public class FOUserAgent {
      * Returns a new {@link Fop} instance. Use this factory method if you want to configure this
      * very rendering run, i.e. if you want to set some metadata like the title and author of the
      * document you want to render. In that case, create a new {@link FOUserAgent}
-     * instance using {@link #newFOUserAgent()}.
+     * instance using {@link org.apache.fop.apps.FopFactory#newFOUserAgent() newFOUserAgent()}.
      * <p>
      * MIME types are used to select the output format (ex. "application/pdf" for PDF). You can
      * use the constants defined in {@link MimeConstants}.
@@ -791,9 +791,8 @@ public class FOUserAgent {
         return factory.getColorSpaceCache();
     }
 
-    /** @see {@link FopFactory#getHyphenationPatternNames()} */
+    /** @see FopFactory#getHyphenationPatternNames() */
     public Map<String, String> getHyphenationPatternNames() {
         return factory.getHyphenationPatternNames();
     }
 }
-

src/java/org/apache/fop/apps/Fop.java

@@ -52,7 +52,7 @@ public class Fop {
     private OutputStream stream = null;
 
     // FOUserAgent object to set processing options
-    private FOUserAgent foUserAgent = null;
+    private final FOUserAgent foUserAgent;
 
     // FOTreeBuilder object to maintain reference for access to results
     private FOTreeBuilder foTreeBuilder = null;
@@ -81,6 +81,10 @@ public class Fop {
     /**
      * Get the FOUserAgent instance associated with the rendering run represented by this instance.
      * @return the user agent
+     *
+     * @deprecated this getter doesn't need to exist. By virtue of the fact that the client has
+     * an instance of this object, it means they also have the {@link FOUserAgent} since this's
+     * constructor is only used in {@link FOUserAgent}
      */
     public FOUserAgent getUserAgent() {
         return foUserAgent;

src/java/org/apache/fop/apps/FopFactory.java

@@ -325,48 +325,41 @@ public final class FopFactory implements ImageContext {
         return config.isAccessibilityEnabled();
     }
 
-    /**
-     * Returns the image manager.
-     * @return the image manager
-     */
+    /** @see FopFactoryConfig#getImageManager() */
     public ImageManager getImageManager() {
         return config.getImageManager();
     }
 
-    /**
-     * Returns the overriding LayoutManagerMaker instance, if any.
-     * @return the overriding LayoutManagerMaker or null
-     */
+    /** @see FopFactoryConfig#getLayoutManagerMakerOverride() */
     public LayoutManagerMaker getLayoutManagerMakerOverride() {
         return config.getLayoutManagerMakerOverride();
     }
 
-    /** @return the hyphenation pattern names */
+    /** @see FopFactoryConfig#getHyphenationPatternNames() */
     public Map<String, String> getHyphenationPatternNames() {
         return config.getHyphenationPatternNames();
     }
 
-    /**
-     * Returns whether FOP is strictly validating input XSL
-     * @return true of strict validation turned on, false otherwise
-     */
+    /** @see FopFactoryConfig#validateStrictly() */
     public boolean validateStrictly() {
         return config.validateStrictly();
     }
 
-    /**
-     * @return true if the indent inheritance should be broken when crossing reference area
-     *         boundaries (for more info, see the javadoc for the relative member variable)
-     */
+    /** @see FopFactoryConfig#isBreakIndentInheritanceOnReferenceAreaBoundary() */
     public boolean isBreakIndentInheritanceOnReferenceAreaBoundary() {
         return config.isBreakIndentInheritanceOnReferenceAreaBoundary();
     }
 
-    /** @return the resolution for resolution-dependent input */
+    /** @see FopFactoryConfig#getSourceResolution() */
     public float getSourceResolution() {
         return config.getSourceResolution();
     }
 
+    /** @see FopFactoryConfig#getTargetResolution() */
+    public float getTargetResolution() {
+        return config.getTargetResolution();
+    }
+
     /**
      * Returns the conversion factor from pixel units to millimeters. This
      * depends on the desired source resolution.
@@ -377,11 +370,6 @@ public final class FopFactory implements ImageContext {
         return UnitConv.IN2MM / getSourceResolution();
     }
 
-    /** @return the resolution for resolution-dependant output */
-    public float getTargetResolution() {
-        return config.getTargetResolution();
-    }
-
     /**
      * Returns the conversion factor from pixel units to millimeters. This
      * depends on the desired target resolution.
@@ -392,42 +380,26 @@ public final class FopFactory implements ImageContext {
         return 25.4f / getTargetResolution();
     }
 
-    /**
-     * Gets the default page-height to use as fallback,
-     * in case page-height="auto"
-     *
-     * @return the page-height, as a String
-     */
+    /** @see FopFactoryConfig#getPageHeight() */
     public String getPageHeight() {
         return config.getPageHeight();
     }
 
-    /**
-     * Gets the default page-width to use as fallback,
-     * in case page-width="auto"
-     *
-     * @return the page-width, as a String
-     */
+    /** @see FopFactoryConfig#getPageWidth() */
     public String getPageWidth() {
         return config.getPageWidth();
     }
 
-    /**
-     * Indicates whether a namespace URI is on the ignored list.
-     * @param namespaceURI the namespace URI
-     * @return true if the namespace is ignored by FOP
-     */
+    /** @see FopFactoryConfig#isNamespaceIgnored(String) */
     public boolean isNamespaceIgnored(String namespaceURI) {
         return config.isNamespaceIgnored(namespaceURI);
     }
 
-    /** @return the set of namespaces that are ignored by FOP */
+    /** @see FopFactoryConfig#getIgnoredNamespaces() */
     public Set<String> getIgnoredNamespace() {
         return config.getIgnoredNamespaces();
     }
 
-    //------------------------------------------- Configuration stuff
-
     /**
      * Get the user configuration.
      * @return the user configuration
@@ -436,20 +408,12 @@ public final class FopFactory implements ImageContext {
         return config.getUserConfig();
     }
 
-    /**
-     * Is the user configuration to be validated?
-     * @return if the user configuration should be validated
-     */
+    /** @see FopFactoryConfig#validateUserConfigStrictly() */
     public boolean validateUserConfigStrictly() {
         return config.validateUserConfigStrictly();
     }
 
-    //------------------------------------------- Font related stuff
-
-    /**
-     * Returns the font manager.
-     * @return the font manager
-     */
+    /** @see FopFactoryConfig#getFontManager() */
     public FontManager getFontManager() {
         return config.getFontManager();
     }

src/java/org/apache/fop/apps/FopFactoryConfig.java

@@ -67,7 +67,10 @@ public interface FopFactoryConfig {
      */
     boolean isAccessibilityEnabled();
 
-    /** @see {@link FopFactory#getLayoutManagerMakerOverride()} */
+    /**
+     * Returns the overriding LayoutManagerMaker instance, if any.
+     * @return the overriding LayoutManagerMaker or null
+     */
     LayoutManagerMaker getLayoutManagerMakerOverride();
 
     /**
@@ -84,31 +87,54 @@ public interface FopFactoryConfig {
      */
     URI getBaseURI();
 
-    /** @see {@link FopFactory#validateStrictly()} */
+    /**
+     * Returns whether FOP is strictly validating input XSL
+     * @return true of strict validation turned on, false otherwise
+     */
     boolean validateStrictly();
 
-    /** @see {@link FopFactory#validateUserConfigStrictly()} */
+    /**
+     * Is the user configuration to be validated?
+     * @return if the user configuration should be validated
+     */
     boolean validateUserConfigStrictly();
 
-    /** @see {@link FopFactory#isBreakIndentInheritanceOnReferenceAreaBoundary()} */
+    /**
+     * @return true if the indent inheritance should be broken when crossing reference area
+     * boundaries (for more info, see the javadoc for the relative member variable)
+     */
     boolean isBreakIndentInheritanceOnReferenceAreaBoundary();
 
-    /** @see {@link FopFactory#getSourceResolution()} */
+    /** @return the resolution for resolution-dependent input */
     float getSourceResolution();
 
-    /** @see {@link FopFactory#getTargetResolution()} */
+    /** @return the resolution for resolution-dependent output */
     float getTargetResolution();
 
-    /** @see {@link FopFactory#getPageHeight()} */
+    /**
+     * Gets the default page-height to use as fallback,
+     * in case page-height="auto"
+     *
+     * @return the page-height, as a String
+     */
     String getPageHeight();
 
-    /** @see {@link FopFactory#getPageWidth()} */
+    /**
+     * Gets the default page-width to use as fallback,
+     * in case page-width="auto"
+     *
+     * @return the page-width, as a String
+     */
     String getPageWidth();
 
-    /** @see {@link FopFactory#getIgnoredNamespace()} */
+    /** @return the set of namespaces that are ignored by FOP */
     Set<String> getIgnoredNamespaces();
 
-    /** @see {@link FopFactory#isNamespaceIgnored(String)} */
+    /**
+     * Indicates whether a namespace URI is on the ignored list.
+     * @param namespace the namespace URI
+     * @return true if the namespace is ignored by FOP
+     */
     boolean isNamespaceIgnored(String namespace);
 
     /**
@@ -118,17 +144,23 @@ public interface FopFactoryConfig {
      */
     Configuration getUserConfig();
 
-    /** @see {@link org.apache.fop.render.RendererFactory#isRendererPreferred()} */
+    /** @see org.apache.fop.render.RendererFactory#isRendererPreferred() */
     boolean preferRenderer();
 
-    /** @see {@link FopFactory#getFontManager()} */
+    /**
+     * Returns the font manager.
+     * @return the font manager
+     */
     FontManager getFontManager();
 
-    /** @see {@link FopFactory#getImageManager()} */
+    /**
+     * Returns the image manager.
+     * @return the image manager
+     */
     ImageManager getImageManager();
 
     boolean isComplexScriptFeaturesEnabled();
 
-    /** @see {@link FopFactory#getHyphenationPatternNames()} */
+    /** @return the hyphenation pattern names */
     Map<String, String> getHyphenationPatternNames();
 }

src/java/org/apache/fop/apps/io/TempResourceResolver.java

@@ -35,7 +35,7 @@ public interface TempResourceResolver {
      * @return the resource
      * @throws IOException if an I/O error occured during resource acquisition
      */
-    Resource getResource(String id) throws IOException;
+    Resource getResource(String uri) throws IOException;
 
     /**
      * Gets an temporary-output stream of a given URI.
@@ -44,5 +44,5 @@ public interface TempResourceResolver {
      * @return the output stream
      * @throws IOException if an I/O error occured while creating an output stream
      */
-    OutputStream getOutputStream(String id) throws IOException;
+    OutputStream getOutputStream(String uri) throws IOException;
 }