Update #30 javadoc of Function and FunctionLineOfCode class

fr.cnes.analysis.tools.shell.metrics/src/fr/cnes/analysis/tools/shell/metrics/Function.java

@@ -2,23 +2,78 @@
 
 import fr.cnes.analysis.tools.analyzer.exception.JFlexException;
 
+/**
+ * This class contains data that are commonly used by metrics to identify a
+ * SHELL function. This can be useful to locate a function and be implemented to
+ * include special details in it.
+ * 
+ * <h2>The starter repetition</h2>
+ * <p>
+ * The {@link #starterRepetition} attribute must be used to count how many times
+ * a structure of control inside the function (that isn't a function itself) is
+ * being started while having the same closing as the instantiated
+ * {@link Function}. This way, it's possible to define on a function element
+ * parsing if it's intended to close the function or a control structure inside
+ * of the function.
+ * </p>
+ * <h2>Exceptions</h2>
+ * <p>
+ * This class throws only {@link JFlexException} to fulfill analyzer
+ * independence of plugging in extension. It's thrown when :
+ * <ul>
+ * <li>It's not possible to reach a finisher for a string requested
+ * <li>While trying to reduce the number of repetition of the starter while it's
+ * value is zero or less</li>
+ * </ul>
+ * 
+ * 
+ * @since 3.0
+ */
 public class Function {
+    /** Function's name */
     private String name;
+    /** Function's line */
     private int beginLine;
+    /** Function starter */
     private String starter;
+    /**
+     * Number of control structure having the same closing as the function's one
+     * inside the function
+     */
     private int starterRepetition;
 
+    /**
+     * Constructor for {@link Function} object.
+     * 
+     * @param pName
+     *            name of the function
+     * @param pBeginLine
+     *            line number of the function
+     * @param pStarter
+     *            element starting the function's body.
+     */
     public Function(final String pName, final int pBeginLine, final String pStarter) {
         this.name = pName;
         this.beginLine = pBeginLine;
         this.starter = pStarter;
         this.starterRepetition = 0;
     }
 
+    /**
+     * Increment the number of structure having the same closing as the current
+     * function
+     */
     public void addStarterRepetition() {
         starterRepetition++;
     }
 
+    /**
+     * Decrement the number of structure having same closing as the current
+     * function. To use on the closing of one of them.
+     * 
+     * @throws JFlexException
+     *             when the number of repetition below or equal zero.
+     */
     public void removeStarterRepetition() throws JFlexException {
         if (starterRepetition > 0) {
             starterRepetition--;
@@ -28,10 +83,23 @@ public void removeStarterRepetition() throws JFlexException {
         }
     }
 
+    /**
+     * @return the {@link String} element that would close the function.
+     * @throws JFlexException
+     */
     public final String getFinisher() throws JFlexException {
         return Function.finisherOf(this.starter);
     }
 
+    /**
+     * @param str
+     *            the {@link String} beginning a control structure or a
+     *            function.
+     * @return the {@link String} which should be considered as the function
+     *         closer of the parameter
+     * @throws JFlexException
+     *             when no finisher can be recognized from the parameter.
+     */
     public static final String finisherOf(String str) throws JFlexException {
         String functionFinisher;
         switch (str) {
@@ -60,11 +128,17 @@ public static final String finisherOf(String str) throws JFlexException {
                 functionFinisher = "]]";
                 break;
             default:
-                throw new JFlexException(new Exception("Function's ender unknown."));
+                throw new JFlexException(new Exception("Function's finisher unknown."));
         }
         return functionFinisher;
     }
 
+    /**
+     * @param str
+     *            the string to compare
+     * @return if the parameter can close the function or not.
+     * @throws JFlexException
+     */
     public final boolean isFinisher(String str) throws JFlexException {
         return str.equals(this.getFinisher());
     }

fr.cnes.analysis.tools.shell.metrics/src/fr/cnes/analysis/tools/shell/metrics/FunctionLineOfCode.java

@@ -1,32 +1,50 @@
 package fr.cnes.analysis.tools.shell.metrics;
 
+/**
+ * This class is intended to count the number of line of a file in SHELL
+ * language. To use this class, read the {@link Function} documentation.
+ * 
+ * @since 3.0
+ */
 public class FunctionLineOfCode extends Function {
-    private String name;
-    private int beginLine;
-    private String starter;
-    private int lineOfCode;
+    /** Number of line of code of the function */
+    private float lineOfCode;
 
+    /**
+     * Constructor mostly for parameter of {@link Function} class. Line of code
+     * is set to zero on new instance.
+     * 
+     * @param pName
+     *            of the function
+     * @param pBeginLine
+     *            of the function
+     * @param pStarter
+     *            {@link String} of the function's body
+     */
     public FunctionLineOfCode(final String pName, final int pBeginLine, final String pStarter) {
         super(pName, pBeginLine, pStarter);
         lineOfCode = 0;
     }
 
+    /**
+     * Increment number of line of code.
+     */
     public void addLineOfCode() {
         this.lineOfCode++;
     }
 
     /**
      * @return the lineOfCode
      */
-    public final int getLineOfCode() {
+    public final float getLineOfCode() {
         return lineOfCode;
     }
 
     /**
      * @param lineOfCode
      *            the lineOfCode to set
      */
-    public final void setLineOfCode(int lineOfCode) {
+    public final void setLineOfCode(float lineOfCode) {
         this.lineOfCode = lineOfCode;
     }