added javadoc for the cache api

scm-core/src/main/java/sonia/scm/SCMContextProvider.java

@@ -40,8 +40,8 @@ import java.io.File;
 
 /**
  * The main class for retrieving the home and the version of the SCM-Manager.
- * This class is a singleton which can be retrieved via
- * inject or with the static {@link SCMContext#getContext()} method.
+ * This class is a singleton which can be retrieved via injection 
+ * or with the static {@link SCMContext#getContext()} method.
  *
  * @author Sebastian Sdorra
  */

scm-core/src/main/java/sonia/scm/cache/Cache.java

@@ -34,59 +34,63 @@
 package sonia.scm.cache;
 
 /**
+ * The main interface for the cache. 
+ * Provides methods to add, access, and remove entries from a cache. 
  *
  * @author Sebastian Sdorra
  *
- * @param <K>
- * @param <V>
+ * @param <K> - The type of the keys for the cache
+ * @param <V> - The type of cache elements
  */
 public interface Cache<K, V>
 {
 
   /**
-   * Method description
+   * Remove all elements from this cache.
    *
    */
   public void clear();
 
   /**
-   * Method description
+   * Returns true if this cache contains an element with the specified key.
    *
    *
-   * @param key
+   * @param key - The key of the cached element
    *
-   * @return
+   * @return true if this cache contains an element with the specified key
    */
   public boolean contains(K key);
 
   /**
-   * Method description
+   * Put a new element to this cache.
    *
    *
-   * @param key
-   * @param value
+   * @param key - The key of the element to cache
+   * @param value - The element that should be cached
    */
   public void put(K key, V value);
 
   /**
-   * Method description
+   * Remove the element with the specified key from this cache. The method
+   * returns true if the operation was successful.
    *
    *
-   * @param key
+   * @param key - The key of the cached element
    *
-   * @return
+   * @return true if the operation was successful
    */
   public boolean remove(K key);
 
   //~--- get methods ----------------------------------------------------------
 
   /**
-   * Method description
+   * Returns the element with the specified key.
+   * Returns null if the cache contains no element with the specified key.
    *
    *
-   * @param key
+   * @param key - The key of the cached element
    *
-   * @return
+   * @return The cached element with the specified key or null
    */
   public V get(K key);
 }

scm-core/src/main/java/sonia/scm/cache/CacheManager.java

@@ -38,6 +38,9 @@ package sonia.scm.cache;
 import java.io.Closeable;
 
 /**
+ * The {@link CacheManager} holds references to {@link Cache} 
+ * and manages their creation.
+ * This class is a singleton which can be retrieved via injection.
  *
  * @author Sebastian Sdorra
  */
@@ -45,16 +48,17 @@ public interface CacheManager extends Closeable
 {
 
   /**
-   * Method description
+   * Returns the cache with the specified types and name. 
+   * If the cache does not exist, a new cache is created.
    *
    *
-   * @param key
-   * @param value
-   * @param name
-   * @param <K>
-   * @param <V>
+   * @param key - The type of the keys for the cache
+   * @param value - The type of cache elements
+   * @param name - The name of the cache
+   * @param <K> - The type of the keys for the cache
+   * @param <V>  - The type of cache elements
    *
-   * @return
+   * @return the cache with the specified types and name
    */
   public <K, V> Cache<K, V> getCache(Class<K> key, Class<V> value, String name);
 }

scm-core/src/main/java/sonia/scm/cache/package-info.java

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) 2010, Sebastian Sdorra
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ * 3. Neither the name of SCM-Manager; nor the names of its
+ *    contributors may be used to endorse or promote products derived from this
+ *    software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * http://bitbucket.org/sdorra/scm-manager
+ *
+ */
+
+
+
+/**
+ * This package contains the cache API.
+ */
+package sonia.scm.cache;