From ed13d7a7fd42b1bcb01694bb0c30cee0440fda16 Mon Sep 17 00:00:00 2001 From: Simon Brandhof Date: Thu, 20 Feb 2014 13:08:22 +0100 Subject: [PATCH] SONAR-926 complete javadoc of org.sonar.api.batch.fs --- .../org/sonar/api/batch/fs/FileSystem.java | 18 ++++++++++++------ .../java/org/sonar/api/batch/fs/InputFile.java | 18 +++++++++++------- .../sonar/api/batch/fs/InputFileFilter.java | 2 +- .../batch/fs/internal/DefaultFileSystem.java | 5 +---- .../batch/fs/internal/DefaultInputFile.java | 12 ++++++------ 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; *

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}:

* 
- *   FileSystem fs = new DefaultFileSystem();
+ *   DefaultFileSystem fs = new DefaultFileSystem();
  *   fs.add(new DefaultInputFile("src/foo/bar.php"));
  *
* @@ -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 * attributes is empty. + *

+ * 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 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 attributes 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 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 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 {@link FileSystem}. - * File separator is the forward slash ('/'), even on Microsoft Windows. + * within given {@link FileSystem}. File separator is the forward + * slash ('/'), even on Microsoft Windows. *

* Returns src/main/java/com/Foo.java if module base dir is - * /absolute/path/to/module and if file is - * /absolute/path/to/module/src/main/java/com/Foo.java. + * /path/to/module and if file is + * /path/to/module/src/main/java/com/Foo.java. *

* 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 -- 2.39.5