added some javadoc for the template engine

scm-core/src/main/java/sonia/scm/template/DefaultEngine.java

@@ -30,6 +30,7 @@
  */
 
 
+
 package sonia.scm.template;
 
 //~--- non-JDK imports --------------------------------------------------------
@@ -44,6 +45,7 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
+ * Identifies the default {@link TemplateEngine}.
  *
  * @author Sebastian Sdorra
  * @since 1.19

scm-core/src/main/java/sonia/scm/template/Template.java

@@ -30,6 +30,7 @@
  */
 
 
+
 package sonia.scm.template;
 
 //~--- JDK imports ------------------------------------------------------------
@@ -38,6 +39,8 @@ import java.io.IOException;
 import java.io.Writer;
 
 /**
+ * The template represents a single template file and is able to render this
+ * template.
  *
  * @author Sebastian Sdorra
  * @since 1.19
@@ -46,12 +49,13 @@ public interface Template
 {
 
   /**
-   * Method description
+   * Renders the template and writes the output to the given writer.
+   * The template will use the given model to replace the placeholder in the
+   * template file.
    *
    *
-   * @param writer
+   * @param writer writer for the rendered template
-   * @param environment
+   * @param model model for the template
-   * @param model
    *
    * @throws IOException
    */

scm-core/src/main/java/sonia/scm/template/TemplateEngine.java

@@ -37,6 +37,8 @@ package sonia.scm.template;
 import java.io.IOException;
 
 /**
+ * The {@link TemplateEngine} searches for {@link Template}s and prepares the 
+ * template for the rendering process.
  *
  * @author Sebastian Sdorra
  * @since 1.19
@@ -45,22 +47,24 @@ public interface TemplateEngine
 {
 
   /**
-   * Method description
+   * Returns the template associated with the given path. The template engine 
+   * will search the template in the folder of the web application and in 
+   * the classpath. This method will return null, 
+   * if no template could be found for the given path.
    *
    *
-   * @param templatePath
+   * @param templatePath path of the template
    *
-   * @return
+   * @return template associated withe the given path or null
    *
    * @throws IOException
    */
   public Template getTemplate(String templatePath) throws IOException;
 
   /**
-   * Method description
+   * Returns the type of this template engine.
    *
-   *
+   * @return type of template engine
-   * @return
    */
   public TemplateType getType();
 }

scm-core/src/main/java/sonia/scm/template/TemplateEngineFactory.java

@@ -30,6 +30,7 @@
  */
 
 
+
 package sonia.scm.template;
 
 //~--- non-JDK imports --------------------------------------------------------
@@ -48,9 +49,14 @@ import java.util.Map;
 import java.util.Set;
 
 /**
+ * The {@link TemplateEngineFactory} is the entrypoint of the template api.
+ * The factory return available template engines. The
+ * {@link TemplateEngineFactory} is available via injection.
  *
  * @author Sebastian Sdorra
  * @since 1.19
+ *
+ * @apiviz.landmark
  */
 @Singleton
 public final class TemplateEngineFactory
@@ -65,11 +71,12 @@ public final class TemplateEngineFactory
   //~--- constructors ---------------------------------------------------------
 
   /**
-   * Constructs ...
+   * Constructs new template engine factory. This constructor should only be
+   * called from the injection framework.
    *
    *
-   * @param engines
+   * @param engines Set of available template engines
-   * @param defaultEngine
+   * @param defaultEngine default template engine
    */
   @Inject
   public TemplateEngineFactory(Set<TemplateEngine> engines,
@@ -104,10 +111,12 @@ public final class TemplateEngineFactory
   //~--- get methods ----------------------------------------------------------
 
   /**
-   * Method description
+   * Returns the default template engine. In the normal case the should be a
+   * implementation of the
+   * <a href="http://mustache.github.com/" target="_blank">mustache template
+   * system</a>.
    *
-   *
+   * @return default template engine
-   * @return
    */
   public TemplateEngine getDefaultEngine()
   {
@@ -115,12 +124,13 @@ public final class TemplateEngineFactory
   }
 
   /**
-   * Method description
+   * Returns template engine by its name. The name of a template engine can be
+   * inquired by calling {@link TemplateType#getName()}. If no engine with the
+   * given name registered this method will return null.
    *
+   * @param engineName name of the engine
    *
-   * @param engineName
+   * @return engine with the given name or null
-   *
-   * @return
    */
   public TemplateEngine getEngine(String engineName)
   {
@@ -128,12 +138,15 @@ public final class TemplateEngineFactory
   }
 
   /**
-   * Method description
+   * Returns template engine by its extension. This method will use the
+   * extension of the given path and search a template engine for this
+   * extension. If no extension could be found in the the path, the method will
+   * handle the whole path as a extension. If no engine could be found for the
+   * given extension, this method will return null.
    *
+   * @param path template path with extension
    *
-   * @param path
+   * @return template engine for the given path or null
-   *
-   * @return
    */
   public TemplateEngine getEngineByExtension(String path)
   {
@@ -159,10 +172,10 @@ public final class TemplateEngineFactory
   }
 
   /**
-   * Method description
+   * Returns all registered template engines.
    *
    *
-   * @return
+   * @return all registered template engines
    */
   public Collection<TemplateEngine> getEngines()
   {
@@ -171,9 +184,9 @@ public final class TemplateEngineFactory
 
   //~--- fields ---------------------------------------------------------------
 
-  /** Field description */
+  /** default template engine */
   private TemplateEngine defaultEngine;
 
-  /** Field description */
+  /** map of registered template engines */
   private Map<String, TemplateEngine> engineMap;
 }

scm-core/src/main/java/sonia/scm/template/TemplateRenderException.java

@@ -37,6 +37,8 @@ package sonia.scm.template;
 import java.io.IOException;
 
 /**
+ * This exception is thrown, if an error during the template rendering 
+ * phase occurs.
  *
  * @author Sebastian Sdorra
  * @since 1.19

scm-core/src/main/java/sonia/scm/template/TemplateType.java

@@ -30,6 +30,7 @@
  */
 
 
+
 package sonia.scm.template;
 
 //~--- non-JDK imports --------------------------------------------------------
@@ -45,20 +46,21 @@ import java.io.Serializable;
 import java.util.Collection;
 
 /**
+ * Represents the type of a {@link TemplateType}.
  *
  * @author Sebastian Sdorra
  * @since 1.19
  */
-public class TemplateType extends Type implements Serializable
+public final class TemplateType extends Type implements Serializable
 {
 
-  /** Field description */
+  /** serial version uid */
   private static final long serialVersionUID = 7947596921895752539L;
 
   //~--- constructors ---------------------------------------------------------
 
   /**
-   * Constructs ...
+   * Constructs new template type.
    *
    *
    * @param name
@@ -73,7 +75,7 @@ public class TemplateType extends Type implements Serializable
   }
 
   /**
-   * Constructs ...
+   * Constructs new template type.
    *
    *
    * @param name
@@ -90,10 +92,10 @@ public class TemplateType extends Type implements Serializable
   //~--- get methods ----------------------------------------------------------
 
   /**
-   * Method description
+   * Returns all extensions associated with this template engine.
    *
    *
-   * @return
+   * @return all extensions
    */
   public Collection<String> getExtensions()
   {
@@ -102,6 +104,6 @@ public class TemplateType extends Type implements Serializable
 
   //~--- fields ---------------------------------------------------------------
 
-  /** Field description */
+  /** extensions */
   private Collection<String> extensions;
 }

scm-core/src/main/java/sonia/scm/template/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
+ *
+ */
+
+
+
+/**
+ * API for template rendering.
+ */
+package sonia.scm.template;