SONAR-926 complete javadoc of org.sonar.api.batch.fs

5 files changed, 31 insertions, 24 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/FileSystem.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/FileSystem.java
index 7d285af934f..4ee79a17481 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/FileSystem.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/FileSystem.java
@@ -30,7 +30,7 @@ import java.util.Set;
  * <p>The unit tests needing an instance of FileSystem can use the implementation
  * {@link org.sonar.api.batch.fs.internal.DefaultFileSystem} and the related {@link org.sonar.api.scan.filesystem.internal.DefaultInputFile}:</p>
  * <pre>
- *   FileSystem fs = new DefaultFileSystem();
+ *   DefaultFileSystem fs = new DefaultFileSystem();
  *   fs.add(new DefaultInputFile("src/foo/bar.php"));
  * </pre>
  *
@@ -58,6 +58,9 @@ public interface FileSystem extends BatchComponent {
   File workDir();
 
   /**
+   * Returns the single element matching the predicate. If more than one elements match
+   * the predicate, then {@link IllegalArgumentException} is thrown. Returns {@code null}
+   * if no files match.
    * @see org.sonar.api.batch.fs.FilePredicates
    */
   @CheckForNull
@@ -66,27 +69,30 @@ public interface FileSystem extends BatchComponent {
   /**
    * Input files matching the given attributes. Return all the files if the parameter
    * <code>attributes</code> is empty.
+   * <p/>
+   * Important - result is an {@link java.lang.Iterable} to benefit from streaming and decreasing
+   * memory consumption. It should be iterated only once, else copy it into a list :
+   * {@code com.google.common.collect.Lists.newArrayList(inputFiles(predicate))}
    * @see org.sonar.api.batch.fs.FilePredicates
    */
   Iterable<InputFile> inputFiles(FilePredicate predicate);
 
   /**
    * Returns true if at least one {@link org.sonar.api.batch.fs.InputFile} matches
-   * the given attributes. This method can be faster than checking if {@link #inputFiles(org.sonar.api.batch.fs.FilePredicate...)}
-   * has elements. If the parameter <code>attributes</code> is empty, then returns true
-   * if at least one input file exists.
+   * the given predicate. This method can be faster than checking if {@link #inputFiles(org.sonar.api.batch.fs.FilePredicate...)}
+   * has elements.
    * @see org.sonar.api.batch.fs.FilePredicates
    */
   boolean hasFiles(FilePredicate predicate);
 
   /**
-   * Files matching the given attributes.
+   * Files matching the given predicate.
    * @see org.sonar.api.batch.fs.FilePredicates
    */
   Iterable<File> files(FilePredicate predicate);
 
   /**
-   * Languages detected in all the files, whatever their type (main code or test)
+   * Languages detected in all files, whatever their type (main or test)
    */
   Set<String> languages();
 }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputFile.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputFile.java
index fb37090325d..b690a12cc2f 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputFile.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputFile.java
@@ -23,7 +23,7 @@ import java.io.File;
 import java.io.Serializable;
 
 /**
- * This layer over {@link java.io.File} adds information useful for code analyzers.
+ * This layer over {@link java.io.File} adds information for code analyzers.
  *
  * @since 4.2
  */
@@ -42,12 +42,12 @@ public interface InputFile extends Serializable {
 
   /**
    * Path relative to module base directory. Path is unique and identifies file
-   * within given <code>{@link FileSystem}</code>.
-   * File separator is the forward slash ('/'), even on Microsoft Windows.
+   * within given <code>{@link FileSystem}</code>. File separator is the forward
+   * slash ('/'), even on Microsoft Windows.
    * <p/>
    * Returns <code>src/main/java/com/Foo.java</code> if module base dir is
-   * <code>/absolute/path/to/module</code> and if file is
-   * <code>/absolute/path/to/module/src/main/java/com/Foo.java</code>.
+   * <code>/path/to/module</code> and if file is
+   * <code>/path/to/module/src/main/java/com/Foo.java</code>.
    * <p/>
    * Relative path is not null and is normalized ('foo/../foo' is replaced by 'foo').
    */
@@ -68,8 +68,8 @@ public interface InputFile extends Serializable {
   File file();
 
   /**
-   * Language, for example "java" or "php". It's automatically guessed when it is not
-   * set by project configuration.
+   * Language, for example "java" or "php". It's automatically guessed if it is not
+   * set in project settings.
    */
   String language();
 
@@ -83,5 +83,9 @@ public interface InputFile extends Serializable {
    */
   Status status();
 
+  /**
+   * Number of physical lines. This method supports all end-of-line characters. Returns
+   * zero if the file is empty.
+   */
   int lines();
 }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputFileFilter.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputFileFilter.java
index d9bdac27857..40d8226ff3b 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputFileFilter.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputFileFilter.java
@@ -22,7 +22,7 @@ package org.sonar.api.batch.fs;
 import org.sonar.api.BatchExtension;
 
 /**
- * Extension point to complete the list of files to ignore during inspection
+ * Extension point to exclude some files from inspection
  * @since 4.2
  */
 public interface InputFileFilter extends BatchExtension {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/internal/DefaultFileSystem.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/internal/DefaultFileSystem.java
index 4754c1aebb1..e5c201e211c 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/internal/DefaultFileSystem.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/internal/DefaultFileSystem.java
@@ -36,10 +36,7 @@ import javax.annotation.CheckForNull;
 import javax.annotation.Nullable;
 import java.io.File;
 import java.nio.charset.Charset;
-import java.util.List;
-import java.util.Map;
-import java.util.NoSuchElementException;
-import java.util.Set;
+import java.util.*;
 
 /**
  * @since 4.2
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/internal/DefaultInputFile.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/internal/DefaultInputFile.java
index fa3f49d0c0a..226a975765c 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/internal/DefaultInputFile.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/internal/DefaultInputFile.java
@@ -94,8 +94,8 @@ public class DefaultInputFile implements InputFile, org.sonar.api.resources.Inpu
   }
 
   /**
-   * Marked as nullable just for the unit tests that do not previously call
-   * {@link #setHash(String)}
+   * Digest hash of the file. Marked as nullable just for the unit tests
+   * that do not previously call {@link #setHash(String)}
    */
   @CheckForNull
   public String hash() {
@@ -108,8 +108,8 @@ public class DefaultInputFile implements InputFile, org.sonar.api.resources.Inpu
   }
 
   /**
-   * Marked as nullable just for the unit tests that do not previously call
-   * {@link #setKey(String)}.
+   * Component key. It's marked as nullable just for the unit tests that
+   * do not previously call {@link #setKey(String)}.
    */
   @CheckForNull
   public String key() {
@@ -157,7 +157,7 @@ public class DefaultInputFile implements InputFile, org.sonar.api.resources.Inpu
   }
 
   /**
-   * Key used before version 4.2. It's different than {@link #key} on Java files.
+   * Key used before version 4.2. It can be different than {@link #key} on Java files.
    */
   public String deprecatedKey() {
     return deprecatedKey;
@@ -212,7 +212,7 @@ public class DefaultInputFile implements InputFile, org.sonar.api.resources.Inpu
   }
 
   /**
-   * @deprecated in 4.2. Use {@link org.sonar.api.batch.fs.FileSystem#baseDir()}
+   * @deprecated in 4.2. Replaced by {@link org.sonar.api.batch.fs.FileSystem#baseDir()}
    */
   @Deprecated
   @Override