From a19af040824349b4be8be4c6f179c2887bf97076 Mon Sep 17 00:00:00 2001 From: Julien HENRY Date: Fri, 8 Sep 2017 10:55:33 +0200 Subject: [PATCH] Improve Javadoc --- .../sonar/api/batch/fs/FilePredicates.java | 21 ++++++++++++------- .../org/sonar/api/batch/fs/InputFile.java | 14 +++++++++---- 2 files changed, 23 insertions(+), 12 deletions(-) diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/FilePredicates.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/FilePredicates.java index c4e1c2e4ebd..58c6de2cb33 100644 --- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/FilePredicates.java +++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/FilePredicates.java @@ -40,11 +40,11 @@ public interface FilePredicates { FilePredicate none(); /** - * Predicate that gets a file by its absolute path. The parameter + * Predicate that find file by its absolute path. The parameter * accepts forward/back slashes as separator and non-normalized values * (/path/to/../foo.txt is same as /path/foo.txt). *

- * Warning - not efficient because absolute path is not indexed yet. + * Warning - may not be supported in SonarLint */ FilePredicate hasAbsolutePath(String s); @@ -53,6 +53,8 @@ public interface FilePredicates { * accepts forward/back slashes as separator and non-normalized values * (foo/../bar.txt is same as bar.txt). It must * not be null. + *

+ * Warning - may not be supported in SonarLint */ FilePredicate hasRelativePath(String s); @@ -86,11 +88,10 @@ public interface FilePredicates { FilePredicate hasURI(URI uri); /** - * Predicate that gets the files which relative or absolute path matches a wildcard pattern. - *
- * If the parameter starts with file:, then absolute path is used, else relative path. Pattern - * is case-sensitive, except for file extension. - *
+ * Predicate that gets the files which "path" matches a wildcard pattern. + *

+ * The path is the path part of the {@link InputFile#uri()}. Pattern is case-sensitive, except for file extension. + *

* Supported wildcards are * and **, but not ?. *
* Examples: @@ -99,7 +100,6 @@ public interface FilePredicates { *

  • **/*Foo*.java matches src/Foo.java, src/BarFoo.java, src/FooBar.java * and src/BarFooBaz.java
    • *
  • **/*FOO.JAVA matches FOO.java and FOO.JAVA but not Foo.java
    • - *
  • file:**/src/*Foo.java matches /path/to/src/Foo.java on unix and c:\path\to\Foo.java on MSWindows
    • * */ FilePredicate matchesPathPattern(String inclusionPattern); @@ -127,9 +127,14 @@ public interface FilePredicates { /** * if the parameter represents an absolute path for the running environment, then * returns {@link #hasAbsolutePath(String)}, else {@link #hasRelativePath(String)} + *

    + * Warning - may not be supported in SonarLint */ FilePredicate hasPath(String s); + /** + * Warning - may not be supported in SonarLint + */ FilePredicate is(File ioFile); FilePredicate hasLanguage(String language); 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 951f8d8ecff..626695a4c21 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 @@ -64,7 +64,7 @@ public interface InputFile extends IndexedFile { * /path/to/module/src/main/java/com/Foo.java. *
    * Relative path is not null and is normalized ('foo/../foo' is replaced by 'foo'). - * @deprecated since 6.6 use {@link #inputStream()}, {@link #filename()} or {@link #uri()} + * @deprecated since 6.6 use {@link #inputStream()} for file content, {@link #filename()} for file name, {@link #uri()} for an unique identifier, and {@link #toString()} for logging */ @Deprecated @Override @@ -76,7 +76,7 @@ public interface InputFile extends IndexedFile { * This is not canonical path. Symbolic links are not resolved. For example if /project/src links * to /tmp/src and basedir is /project, then this method returns /project/src/index.php. Use * {@code file().getCanonicalPath()} to resolve symbolic link. - * @deprecated since 6.6 use {@link #inputStream()}, {@link #filename()} or {@link #uri()} + * @deprecated since 6.6 use {@link #inputStream()} for file content, {@link #filename()} for file name, {@link #uri()} for an unique identifier, and {@link #toString()} for logging */ @Deprecated @Override @@ -86,7 +86,7 @@ public interface InputFile extends IndexedFile { * The underlying absolute {@link java.io.File}. It should not be used to read the file in the filesystem. * @see #contents() * @see #inputStream() - * @deprecated since 6.6 use {@link #inputStream()}, {@link #filename()} or {@link #uri()} + * @deprecated since 6.6 use {@link #inputStream()} for file content, {@link #filename()} for file name, {@link #uri()} for an unique identifier, and {@link #toString()} for logging */ @Deprecated @Override @@ -98,7 +98,7 @@ public interface InputFile extends IndexedFile { * @see #contents() * @see #inputStream() * @since 5.1 - * @deprecated since 6.6 use {@link #inputStream()}, {@link #filename()} or {@link #uri()} + * @deprecated since 6.6 use {@link #inputStream()} for file content, {@link #filename()} for file name, {@link #uri()} for an unique identifier, and {@link #toString()} for logging */ @Deprecated @Override @@ -197,4 +197,10 @@ public interface InputFile extends IndexedFile { * @since 6.0 */ Charset charset(); + + /** + * Return a string to identify this file (suitable for logs). + */ + @Override + String toString(); } -- 2.39.5