fix some javadoc warnings

2025-11-13 08:55:44 +01:00 · 2013-05-30 09:27:32 +02:00
parent 3a454fcedb
commit f9bc3aafe9
24 changed files with 52 additions and 127 deletions
--- a/scm-core/src/main/java/sonia/scm/BasicContextProvider.java
+++ b/scm-core/src/main/java/sonia/scm/BasicContextProvider.java
@@ -108,17 +108,13 @@ public class BasicContextProvider implements SCMContextProvider
  //~--- methods --------------------------------------------------------------

  /**
-   * {@see java.io.Closeable#close()}
-   *
-   *
-   * @throws IOException
+   * {@inheritDoc}
   */
  @Override
  public void close() throws IOException {}

  /**
-   * {@see SCMContextProvider#init()}
-   *
+   * {@inheritDoc}
   */
  @Override
  public void init() {}
@@ -126,10 +122,7 @@ public class BasicContextProvider implements SCMContextProvider
  //~--- get methods ----------------------------------------------------------

  /**
-   * {@see SCMContextProvider#getBaseDirectory()}
-   *
-   *
-   * @return {@see SCMContextProvider#getBaseDirectory()}
+   * {@inheritDoc}
   */
  @Override
  public File getBaseDirectory()
@@ -139,8 +132,6 @@ public class BasicContextProvider implements SCMContextProvider

  /**
   * {@inheritDoc}
-   *
-   * @return
   */
  @Override
  public Stage getStage()
@@ -150,9 +141,6 @@ public class BasicContextProvider implements SCMContextProvider

  /**
   * {@inheritDoc}
-   *
-   *
-   * @return
   */
  @Override
  public Throwable getStartupError()
--- a/scm-core/src/main/java/sonia/scm/ManagerDecorator.java
+++ b/scm-core/src/main/java/sonia/scm/ManagerDecorator.java
@@ -40,23 +40,23 @@ import java.util.Collection;
 import java.util.Comparator;

 /**
- * Basic decorator for manager classes
+ * Basic decorator for manager classes.
 *
 * @author Sebastian Sdorra
 * @since 1.23
 *
- * @param <T>
- * @param <E>
+ * @param <T> model type
+ * @param <E> exception type
 */
 public class ManagerDecorator<T extends ModelObject, E extends Exception>
  implements Manager<T, E>
 {

  /**
-   * Constructs ...
+   * Constructs a new ManagerDecorator.
   *
   *
-   * @param decorated
+   * @param decorated manager implementation
   */
  public ManagerDecorator(Manager<T, E> decorated)
  {
@@ -67,9 +67,6 @@ public class ManagerDecorator<T extends ModelObject, E extends Exception>

  /**
   * {@inheritDoc}
-   *
-   *
-   * @throws IOException
   */
  @Override
  public void close() throws IOException
@@ -79,12 +76,6 @@ public class ManagerDecorator<T extends ModelObject, E extends Exception>

  /**
   * {@inheritDoc}
-   *
-   *
-   * @param object
-   *
-   * @throws E
-   * @throws IOException
   */
  @Override
  public void create(T object) throws E, IOException
@@ -94,12 +85,6 @@ public class ManagerDecorator<T extends ModelObject, E extends Exception>

  /**
   * {@inheritDoc}
-   *
-   *
-   * @param object
-   *
-   * @throws E
-   * @throws IOException
   */
  @Override
  public void delete(T object) throws E, IOException
@@ -109,9 +94,6 @@ public class ManagerDecorator<T extends ModelObject, E extends Exception>

  /**
   * {@inheritDoc}
-   *
-   *
-   * @param context
   */
  @Override
  public void init(SCMContextProvider context)
@@ -121,12 +103,6 @@ public class ManagerDecorator<T extends ModelObject, E extends Exception>

  /**
   * {@inheritDoc}
-   *
-   *
-   * @param object
-   *
-   * @throws E
-   * @throws IOException
   */
  @Override
  public void modify(T object) throws E, IOException
@@ -136,12 +112,6 @@ public class ManagerDecorator<T extends ModelObject, E extends Exception>

  /**
   * {@inheritDoc}
-   *
-   *
-   * @param object
-   *
-   * @throws E
-   * @throws IOException
   */
  @Override
  public void refresh(T object) throws E, IOException
@@ -153,11 +123,6 @@ public class ManagerDecorator<T extends ModelObject, E extends Exception>

  /**
   * {@inheritDoc}
-   *
-   *
-   * @param id
-   *
-   * @return
   */
  @Override
  public T get(String id)
@@ -167,9 +132,6 @@ public class ManagerDecorator<T extends ModelObject, E extends Exception>

  /**
   * {@inheritDoc}
-   *
-   *
-   * @return
   */
  @Override
  public Collection<T> getAll()
@@ -179,11 +141,6 @@ public class ManagerDecorator<T extends ModelObject, E extends Exception>

  /**
   * {@inheritDoc}
-   *
-   *
-   * @param comparator
-   *
-   * @return
   */
  @Override
  public Collection<T> getAll(Comparator<T> comparator)
@@ -193,12 +150,6 @@ public class ManagerDecorator<T extends ModelObject, E extends Exception>

  /**
   * {@inheritDoc}
-   *
-   *
-   * @param start
-   * @param limit
-   *
-   * @return
   */
  @Override
  public Collection<T> getAll(int start, int limit)
@@ -208,13 +159,6 @@ public class ManagerDecorator<T extends ModelObject, E extends Exception>

  /**
   * {@inheritDoc}
-   *
-   *
-   * @param comparator
-   * @param start
-   * @param limit
-   *
-   * @return
   */
  @Override
  public Collection<T> getAll(Comparator<T> comparator, int start, int limit)
@@ -224,9 +168,6 @@ public class ManagerDecorator<T extends ModelObject, E extends Exception>

  /**
   * {@inheritDoc}
-   *
-   *
-   * @return
   */
  @Override
  public Long getLastModified()
@@ -236,6 +177,6 @@ public class ManagerDecorator<T extends ModelObject, E extends Exception>

  //~--- fields ---------------------------------------------------------------

-  /** Field description */
+  /** manager implementation */
  private Manager<T, E> decorated;
 }
--- a/scm-core/src/main/java/sonia/scm/ServletContainerDetector.java
+++ b/scm-core/src/main/java/sonia/scm/ServletContainerDetector.java
@@ -261,12 +261,12 @@ public class ServletContainerDetector
  //~--- methods --------------------------------------------------------------

  /**
-   * Method description
+   * Returns true if the given class exists in the system classpath.
   *
   *
-   * @param clazz
+   * @param clazz class name to search in classpath
   *
-   * @return
+   * @return true if class exists in system classpath
   */
  private boolean detect(String clazz)
  {
--- a/scm-core/src/main/java/sonia/scm/Stage.java
+++ b/scm-core/src/main/java/sonia/scm/Stage.java
@@ -35,7 +35,7 @@ package sonia.scm;
 /**
 * The constants in this class represent the current state of the running
 * SCM_Manager instance. The stage can be queried by calling
- * {@link SCMContextProvider#getProjectStage()}.
+ * {@link SCMContextProvider#getStage()}.
 *
 * @author Sebastian Sdorra
 * @since 1.12
--- a/scm-core/src/main/java/sonia/scm/config/ScmConfiguration.java
+++ b/scm-core/src/main/java/sonia/scm/config/ScmConfiguration.java
@@ -226,11 +226,10 @@ public class ScmConfiguration

  /**
   * Returns the date format for the user interface. This format is a
-   * JavaScript date format, see
-   * {@link http://jacwright.com/projects/javascript/date_format}.
-   *
-   *
-   * @return JavaScript date format
+   * JavaScript date format, from the library moment.js.
+   * 
+   * @see <a href="http://momentjs.com/docs/#/parsing/" target="_blank">http://momentjs.com/docs/#/parsing/</a>
+   * @return moment.js date format
   */
  public String getDateFormat()
  {
@@ -486,10 +485,10 @@ public class ScmConfiguration
  }

  /**
-   * Method description
+   * Sets the date format for the ui.
   *
   *
-   * @param dateFormat
+   * @param dateFormat date format for ui
   */
  public void setDateFormat(String dateFormat)
  {
@@ -752,7 +751,8 @@ public class ScmConfiguration
  private boolean disableGroupingGrid = false;

  /**
-   * JavaScript date format, see http://jacwright.com/projects/javascript/date_format
+   * JavaScript date format from moment.js
+   * @see <a href="http://momentjs.com/docs/#/parsing/" target="_blank">http://momentjs.com/docs/#/parsing/</a>
   */
  private String dateFormat = DEFAULT_DATEFORMAT;

--- a/scm-core/src/main/java/sonia/scm/event/ScmEventBus.java
+++ b/scm-core/src/main/java/sonia/scm/event/ScmEventBus.java
@@ -36,6 +36,7 @@ package sonia.scm.event;
 //~--- non-JDK imports --------------------------------------------------------

 import com.google.common.eventbus.EventBus;
+import com.google.common.eventbus.Subscribe;

 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -51,7 +52,7 @@ import java.util.ServiceLoader;
 * themselves. The ScmEventBus searches its implementation with the
 * {@link ServiceLoader}.
 *
- * @see {@link EventBus}
+ * @see EventBus
 * @author Sebastian Sdorra
 * @since 1.23
 *
--- a/scm-core/src/main/java/sonia/scm/event/Subscriber.java
+++ b/scm-core/src/main/java/sonia/scm/event/Subscriber.java
@@ -55,9 +55,9 @@ import sonia.scm.EagerSingleton;
 * {@link EagerSingleton} scope for your object. E.g.:
 * 
 * <pre><code>
- *   @Extension
- *   @Subscriber
- *   @EagerSingleton
+ *   {@code @}Extension
+ *   {@code @}Subscriber
+ *   {@code @}EagerSingleton
 *   public class MyListener {
 * 
 *     @Subscribe
--- a/scm-core/src/main/java/sonia/scm/filter/GZipFilterConfig.java
+++ b/scm-core/src/main/java/sonia/scm/filter/GZipFilterConfig.java
@@ -71,11 +71,9 @@ public class GZipFilterConfig
  /**
   * Enables or disables response buffering. Default buffering is enabled.
   *
-   *
-   * @param bufferRequest true to enabled response buffering.
+   * @param bufferResponse true to enabled response buffering.
+   * 
   * @deprecated use {@link #setBufferResponse(boolean)} instead.
-   *
-   * @param bufferResponse
   */
  @Deprecated
  public void setBufferRequest(boolean bufferResponse)
@@ -86,10 +84,7 @@ public class GZipFilterConfig
  /**
   * Enables or disables response buffering. Default buffering is enabled.
   *
-   *
-   * @param bufferRequest true to enabled response buffering.
-   *
-   * @param bufferResponse
+   * @param bufferResponse true to enabled response buffering.
   */
  public void setBufferResponse(boolean bufferResponse)
  {
--- a/scm-core/src/main/java/sonia/scm/group/GroupNotFoundException.java
+++ b/scm-core/src/main/java/sonia/scm/group/GroupNotFoundException.java
@@ -34,7 +34,7 @@ package sonia.scm.group;

 /**
 * The GroupNotFoundException is thrown e.g. from the
- * {@link GroupManager#modify(Group)} if the group does not exists.
+ * modify method of the {@link GroupManager}, if the group does not exists.
 *
 * @author Sebastian Sdorra
 *
--- a/scm-core/src/main/java/sonia/scm/io/DeepCopy.java
+++ b/scm-core/src/main/java/sonia/scm/io/DeepCopy.java
@@ -48,7 +48,7 @@ import java.io.ObjectOutputStream;
 *
 * @author Sebastian Sdorra
 * @since 1.29
- * @see http://javatechniques.com/blog/faster-deep-copies-of-java-objects
+ * @see <a href="http://javatechniques.com/blog/faster-deep-copies-of-java-objects" target="_blank">http://javatechniques.com/blog/faster-deep-copies-of-java-objects</a>
 */
 public final class DeepCopy
 {
--- a/scm-core/src/main/java/sonia/scm/io/FastByteArrayInputStream.java
+++ b/scm-core/src/main/java/sonia/scm/io/FastByteArrayInputStream.java
@@ -41,7 +41,7 @@ import java.io.InputStream;
 *
 * @author Sebastian Sdorra
 * @since 1.29
- * @see http://javatechniques.com/blog/faster-deep-copies-of-java-objects
+ * @see <a href="http://javatechniques.com/blog/faster-deep-copies-of-java-objects" target="_blank">http://javatechniques.com/blog/faster-deep-copies-of-java-objects</a>
 */
 public final class FastByteArrayInputStream extends InputStream
 {
--- a/scm-core/src/main/java/sonia/scm/io/FastByteArrayOutputStream.java
+++ b/scm-core/src/main/java/sonia/scm/io/FastByteArrayOutputStream.java
@@ -43,7 +43,7 @@ import java.io.OutputStream;
 *
 * @author Sebastian Sdorra
 * @since 1.29
- * @see http://javatechniques.com/blog/faster-deep-copies-of-java-objects
+ * @see <a href="http://javatechniques.com/blog/faster-deep-copies-of-java-objects" target="_blank">http://javatechniques.com/blog/faster-deep-copies-of-java-objects</a>
 */
 public final class FastByteArrayOutputStream extends OutputStream
 {
--- a/scm-core/src/main/java/sonia/scm/net/ChildFirstURLClassLoader.java
+++ b/scm-core/src/main/java/sonia/scm/net/ChildFirstURLClassLoader.java
@@ -114,7 +114,7 @@ public class ChildFirstURLClassLoader extends URLClassLoader
   * </ol>
   *
   * If the class was found using the above steps, and the {@code resolve} flag
-   * is true, this method will then invoke the {@link resolveClass(Class)}
+   * is true, this method will then invoke the {@link #resolveClass(Class)}
   * method on the resulting Class object. Subclasses of ClassLoader are
   * encouraged to override {@link ClassLoader#findClass(String)}, rather than
   * this method.
--- a/scm-core/src/main/java/sonia/scm/repository/PermissionUtil.java
+++ b/scm-core/src/main/java/sonia/scm/repository/PermissionUtil.java
@@ -151,7 +151,7 @@ public final class PermissionUtil
   * @param pt
   *
   * @return
-   * @deprecated use {@link #hasPermission(Repository,PermissionType)} instead
+   * @deprecated use {@link #hasPermission(ScmConfiguration, Repository, PermissionType)} instead
   */
  @Deprecated
  public static boolean hasPermission(Repository repository,
--- a/scm-core/src/main/java/sonia/scm/repository/PreProcessorUtil.java
+++ b/scm-core/src/main/java/sonia/scm/repository/PreProcessorUtil.java
@@ -216,7 +216,6 @@ public class PreProcessorUtil
   *
   *
   * @param repository
-   * @param changeset
   * @param result
   */
  public void prepareForReturn(Repository repository, BrowserResult result)
--- a/scm-core/src/main/java/sonia/scm/repository/RepositoryHookSupport.java
+++ b/scm-core/src/main/java/sonia/scm/repository/RepositoryHookSupport.java
@@ -62,7 +62,7 @@ public interface RepositoryHookSupport

  /**
   * Fires a post receive hook event. This methods calls the
-   * {@link PostReceiveRepositoryHook#onPostReceive(Repository, List)} 
+   * {@link PostReceiveRepositoryHook#onEvent(RepositoryHookEvent)} 
   * of each registered {@link PostReceiveRepositoryHook}.
   *
   * @param repository that has changed
@@ -72,7 +72,7 @@ public interface RepositoryHookSupport

  /**
   * Fires a post receive hook event. This methods calls the
-   * {@link PostReceiveRepositoryHook#onPostReceive(Repository, List)} 
+   * {@link PostReceiveRepositoryHook#onEvent(RepositoryHookEvent)} 
   * of each registered {@link PostReceiveRepositoryHook}.
   *
   *
--- a/scm-core/src/main/java/sonia/scm/repository/api/AbstractPushOrPullResponse.java
+++ b/scm-core/src/main/java/sonia/scm/repository/api/AbstractPushOrPullResponse.java
@@ -56,10 +56,7 @@ public abstract class AbstractPushOrPullResponse
  /**
   * Constructs a new AbstractPushOrPullResponse.
   *
-   *
-   * @param pushedChangesetCount count of pushed/pulled changesets
-   *
-   * @param changesetCount
+   * @param changesetCount count of pushed/pulled changesets
   */
  public AbstractPushOrPullResponse(long changesetCount)
  {
--- a/scm-core/src/main/java/sonia/scm/repository/api/BrowseCommandBuilder.java
+++ b/scm-core/src/main/java/sonia/scm/repository/api/BrowseCommandBuilder.java
@@ -222,7 +222,7 @@ public final class BrowseCommandBuilder
  /**
   * Disabling the last commit means that every call to
   * {@link FileObject#getDescription()} and
-   * {@link FileObject#getLastModified()) will return {@code null}, but this
+   * {@link FileObject#getLastModified()} will return {@code null}, but this
   * will also reduce the execution time.
   *
   *
--- a/scm-core/src/main/java/sonia/scm/repository/api/IncomingCommandBuilder.java
+++ b/scm-core/src/main/java/sonia/scm/repository/api/IncomingCommandBuilder.java
@@ -33,11 +33,11 @@ package sonia.scm.repository.api;

 //~--- non-JDK imports --------------------------------------------------------

-import java.io.IOException;
 import org.apache.shiro.SecurityUtils;
 import org.apache.shiro.subject.Subject;

 import sonia.scm.cache.CacheManager;
+import sonia.scm.repository.Changeset;
 import sonia.scm.repository.ChangesetPagingResult;
 import sonia.scm.repository.PermissionType;
 import sonia.scm.repository.PreProcessorUtil;
@@ -47,6 +47,10 @@ import sonia.scm.repository.spi.IncomingCommand;
 import sonia.scm.repository.spi.IncomingCommandRequest;
 import sonia.scm.security.RepositoryPermission;

+//~--- JDK imports ------------------------------------------------------------
+
+import java.io.IOException;
+
 /**
 * The incoming command shows new {@link Changeset}s found in a different
 * repository location.
@@ -62,6 +66,8 @@ public final class IncomingCommandBuilder
   * only be called from the {@link RepositoryService}.
   *
   * @param cacheManager cache manager
+   *
+   * @param cacheManger
   * @param command implementation of the {@link IncomingCommand}
   * @param repository repository to query
   * @param preProcessorUtil pre processor util
@@ -82,9 +88,13 @@ public final class IncomingCommandBuilder
   * @param remoteRepository remote repository
   *
   * @return incoming changesets
+   *
+   * @throws IOException
+   * @throws RepositoryException
   */
  public ChangesetPagingResult getIncomingChangesets(
-    Repository remoteRepository) throws IOException, RepositoryException
+    Repository remoteRepository)
+    throws IOException, RepositoryException
  {
    Subject subject = SecurityUtils.getSubject();

--- a/scm-core/src/main/java/sonia/scm/repository/api/RepositoryServiceFactory.java
+++ b/scm-core/src/main/java/sonia/scm/repository/api/RepositoryServiceFactory.java
@@ -130,7 +130,6 @@ public final class RepositoryServiceFactory
   *
   * @param cacheManager cache manager
   * @param repositoryManager manager for repositories
-   * @param securityContextProvider provider for the current security context
   * @param resolvers a set of {@link RepositoryServiceResolver}
   * @param preProcessorUtil helper object for pre processor handling
   *
--- a/scm-core/src/main/java/sonia/scm/repository/spi/RemoteCommandRequest.java
+++ b/scm-core/src/main/java/sonia/scm/repository/spi/RemoteCommandRequest.java
@@ -94,9 +94,6 @@ public abstract class RemoteCommandRequest
  /**
   * Method description
   *
-   *
-   * @param remoteRepository
-   *
   * @param remoteRepository
   */
  public void setRemoteRepository(Repository remoteRepository)
--- a/scm-core/src/main/java/sonia/scm/security/SHA1HashBuilder.java
+++ b/scm-core/src/main/java/sonia/scm/security/SHA1HashBuilder.java
@@ -120,7 +120,6 @@ public class SHA1HashBuilder extends MessageDigestHashBuilder
   * @param salt
   * @param iterations
   * @param appendSalt
-   * @param enableLable
   * @param enableLabel
   */
  public SHA1HashBuilder(String value, byte[] salt, int iterations,
--- a/scm-core/src/main/java/sonia/scm/user/UserNotFoundException.java
+++ b/scm-core/src/main/java/sonia/scm/user/UserNotFoundException.java
@@ -34,7 +34,7 @@ package sonia.scm.user;

 /**
 * The UserNotFoundException is thrown e.g. from the
- * {@link UserManager#modify(User)} if the user does not exists.
+ * modify method of the {@link UserManager}, if the user does not exists.
 *
 * @author Sebastian Sdorra
 * @since 1.28
--- a/scm-core/src/main/java/sonia/scm/web/filter/RegexPermissionFilter.java
+++ b/scm-core/src/main/java/sonia/scm/web/filter/RegexPermissionFilter.java
@@ -68,7 +68,6 @@ public abstract class RegexPermissionFilter extends PermissionFilter
   *
   *
   * @param configuration
-   * @param securityContextProvider
   * @param repositoryManager
   */
  public RegexPermissionFilter(ScmConfiguration configuration,