Merge pull request #257 from headius/fix_javadoc

Fix javadoc lint issues

Author: headius

src/main/java/org/jruby/rack/AbstractFilter.java

@@ -42,11 +42,11 @@ public abstract class AbstractFilter implements Filter {
 
     /**
      * @see Filter#doFilter(ServletRequest, ServletResponse, FilterChain)
-     * @param request
-     * @param response
-     * @param chain
-     * @throws IOException
-     * @throws ServletException
+     * @param request the request
+     * @param response the response
+     * @param chain the FilterChain
+     * @throws IOException if there's an IO exception
+     * @throws ServletException if there's a servlet exception
      */
     public final void doFilter(
             ServletRequest request, ServletResponse response,
@@ -82,11 +82,15 @@ public void destroy() {
      * requests are given to the {@link RackDispatcher}, but you can extend
      * this method and return false if you want to signal that you don't want
      * the {@link RackDispatcher} to see the request.
-
+     *
+     * @param request the request
+     * @param response the response
+     * @param chain the FilterChain
+     * @param env the RackEnvironent
      * @return true if the dispatcher should handle the request, false if it
      * shouldn't.
-     * @throws IOException
-     * @throws ServletException
+     * @throws IOException if there's an IO exception
+     * @throws ServletException if there's a servlet exception
      */
     protected boolean isDoDispatch(
             RequestCapture request, ResponseCapture response,
@@ -97,6 +101,14 @@ protected boolean isDoDispatch(
 
     /**
      * @deprecated use {@link #isDoDispatch(RequestCapture, ResponseCapture, FilterChain, RackEnvironment)}
+     * @param request the request
+     * @param response the response
+     * @param chain the FilterChain
+     * @param env the RackEnvironent
+     * @param responseEnv the RackResponseEnvironment
+     * @return isDoDispatch
+     * @throws IOException if there's an IO exception
+     * @throws ServletException if there's a servlet exception
      */
     @Deprecated
     protected boolean isDoDispatch(
@@ -109,7 +121,7 @@ protected boolean isDoDispatch(
 
     /**
      * Extension point if you'll need to customize {@link RequestCapture}
-     * @param request
+     * @param request the request
      * @return request capture
      */
     protected RequestCapture wrapRequest(ServletRequest request) {
@@ -118,7 +130,7 @@ protected RequestCapture wrapRequest(ServletRequest request) {
 
     /**
      * Extension point if you'll need to customize {@link ResponseCapture}
-     * @param response
+     * @param response the response
      * @return response capture
      */
     protected ResponseCapture wrapResponse(ServletResponse response) {

src/main/java/org/jruby/rack/DefaultRackApplication.java

@@ -17,7 +17,7 @@
  * (which is wrapped in a <code>Rack::Handler::Servlet</code> instance).
  * Returns the response converted to a Java {@link RackResponse} object.
  *
- * @see rack/handler/servlet.rb
+ * See src/main/ruby/rack/handler/servlet.rb
  *
  * @author nicksieger
  */
@@ -34,8 +34,8 @@ public class DefaultRackApplication implements RackApplication {
     public DefaultRackApplication() { /* NOOP */ }
 
     /**
-     * @see #setApplication(IRubyObject)
-     * @param application
+     * @see DefaultRackApplication#setApplication(IRubyObject)
+     * @param application the application object
      */
     public DefaultRackApplication(final IRubyObject application) {
         this();
@@ -88,7 +88,7 @@ public IRubyObject getApplication() {
 
     /**
      * Sets the application object.
-     * @param application
+     * @param application the application
      */
     public void setApplication(IRubyObject application) {
         this.application = application;

src/main/java/org/jruby/rack/DefaultRackApplicationFactory.java

@@ -75,9 +75,9 @@ public void setRackupScript(String rackupScript) {
 
     /**
      * Initialize this factory using the given context.
-     * <br/>
+     *
      * NOTE: exception handling is left to the outer factory.
-     * @param rackContext
+     * @param rackContext the RackContext
      */
     @Override
     public void init(final RackContext rackContext) {
@@ -93,7 +93,7 @@ public void init(final RackContext rackContext) {
 
     /**
      * Creates a new application instance (without initializing it).
-     * <br/>
+     *
      * NOTE: exception handling is left to the outer factory.
      * @return new application instance
      */
@@ -108,7 +108,7 @@ public IRubyObject create(Ruby runtime) {
 
     /**
      * Creates a new application and initializes it.
-     * <br/>
+     *
      * NOTE: exception handling is left to the outer factory.
      * @return new, initialized application
      */
@@ -121,7 +121,7 @@ public RackApplication getApplication() {
 
     /**
      * Destroys the application (assumably) created by this factory.
-     * <br/>
+     *
      * NOTE: exception handling is left to the outer factory.
      * @param app the application to "release"
      */
@@ -147,7 +147,7 @@ public RackApplication getErrorApplication() {
 
     /**
      * Set the (default) error application to be used.
-     * @param errorApplication
+     * @param errorApplication the error application
      */
     public synchronized void setErrorApplication(RackApplication errorApplication) {
         this.errorApplication = errorApplication;
@@ -227,8 +227,8 @@ public IRubyObject create(Ruby runtime) {
 
     /**
      * @see #createRackServletWrapper(Ruby, String, String)
-     * @param runtime
-     * @param rackup
+     * @param runtime the JRuby runtime
+     * @param rackup the rackup string
      * @return (Ruby) built Rack Servlet handler
      */
     protected IRubyObject createRackServletWrapper(Ruby runtime, String rackup) {
@@ -237,9 +237,9 @@ protected IRubyObject createRackServletWrapper(Ruby runtime, String rackup) {
 
     /**
      * Creates the handler to bridge the Servlet and Rack worlds.
-     * @param runtime
-     * @param rackup
-     * @param filename
+     * @param runtime the JRuby runtime
+     * @param rackup the rackup string
+     * @param filename the filename
      * @return (Ruby) built Rack Servlet handler
      */
     protected IRubyObject createRackServletWrapper(Ruby runtime, String rackup, String filename) {

src/main/java/org/jruby/rack/PoolingRackApplicationFactory.java

@@ -192,7 +192,7 @@ else if ( permit && ( initialSize != null &&
 
     /**
      * @return true if a permit is acquired, false if no permit necessary
-     * @throws TimeoutException if a permit can not be acquired
+     * @throws AcquireTimeoutException if a permit can not be acquired
      */
     protected boolean acquireApplicationPermit() throws AcquireTimeoutException {
         // NOTE: permits are only used if a pool maximum is specified !
@@ -276,7 +276,7 @@ public void fillInitialPool() throws RackInitializationException {
     }
 
     /**
-     * @param apps
+     * @param apps a queue of apps
      * @deprecated override {@link #launchInitialization(java.util.Queue)}
      */
     @Deprecated

src/main/java/org/jruby/rack/RackApplication.java

@@ -18,13 +18,20 @@ public interface RackApplication {
     void init() throws RackInitializationException;
     void destroy();
 
-    /** Make a request into the Rack-based Ruby web application. */
+    /**
+     * Make a request into the Rack-based Ruby web application.
+     *
+     * @param env the RackEnvironment
+     * @return the RackResponse
+     */
     public RackResponse call(RackEnvironment env);
 
     /**
      * Get a reference to the underlying runtime that holds the application
      * and supporting code. Useful for embedding environments that wish to access
      * the application without entering through the web request/response cycle.
+     *
+     * @return the JRuby runtime
      */
     Ruby getRuntime();
 }

src/main/java/org/jruby/rack/RackApplicationFactory.java

@@ -20,32 +20,40 @@ public interface RackApplicationFactory {
 
     /** 
      * Initialize the factory (using the given context).
-     * @param rackContext
+     *
+     * @param rackContext the context
      */
     void init(RackContext rackContext) throws RackInitializationException;
 
     /** 
      * Create a new, uninitialized application. The resulting object must be 
      * initialized by calling its {@link RackApplication#init} method.
+     *
+     * @return a new application
      */
     RackApplication newApplication() throws RackException;
 
     /** 
      * Retrieve an application that is ready to use, possibly creating one 
      * if it's necessary.
+     *
+     * @return the application
      */
     RackApplication getApplication() throws RackException;
 
     /** 
      * Return the application to the factory after processing. 
      * e.g. for allowing the application to be pooled and/or cleaned up.
+     * @param app the application
      */
     void finishedWithApplication(RackApplication app);
 
     /** 
      * Get the designated error application. 
      * The error application is expected to be a singleton and should not be 
-     * returned to the factory. 
+     * returned to the factory.
+     *
+     * @return the error application
      */
     RackApplication getErrorApplication(); // TODO return ErrorApplication
 

src/main/java/org/jruby/rack/RackApplicationFactoryDecorator.java

@@ -85,7 +85,7 @@ public RuntimeException getInitError() {
 
     /**
      * Allows to set the initialization error for concrete factories.
-     * @param initError
+     * @param initError the initialization error to raise
      * @see #getApplication()
      */
     protected synchronized void setInitError(RuntimeException initError) {
@@ -94,8 +94,8 @@ protected synchronized void setInitError(RuntimeException initError) {
 
     /**
      * @see RackApplicationFactory#init(RackContext)
-     * @param context
-     * @throws RackInitializationException
+     * @param context the current RackContext
+     * @throws RackInitializationException if there's an error while initializing
      */
     @Override
     public void init(final RackContext context) throws RackInitializationException {
@@ -110,6 +110,7 @@ public void init(final RackContext context) throws RackInitializationException {
 
     /**
      * Perform the initialization for this factory.
+     * @throws Exception if there's an exception
      */
     protected void doInit() throws Exception {
         getDelegate().init(context);
@@ -130,7 +131,7 @@ public void destroy() {
      * factory.
      * @see RackApplicationFactory#getApplication()
      * @see #getApplicationImpl()
-     * @throws RackException
+     * @throws RackException if there is a failure to initialize
      */
     @Override
     public RackApplication getApplication() throws RackException {
@@ -165,8 +166,8 @@ protected RackConfig getConfig() {
 
     /**
      * Log a message.
-     * @param level
-     * @param message
+     * @param level the logger level
+     * @param message the log message
      */
     protected void log(final RackLogger.Level level, final String message) {
         getContextBang().log(level, message);
@@ -179,9 +180,9 @@ protected void log(final String level, final String message) {
 
     /**
      * Log a message (and an exception).
-     * @param level
-     * @param message
-     * @param e
+     * @param level the logger level
+     * @param message the log message
+     * @param e the exception raised
      */
     protected void log(final RackLogger.Level level, final String message, Exception e) {
         getContextBang().log(level, message, e);