Improve Javadoc

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
    * (<code>/path/to/../foo.txt</code> is same as <code>/path/foo.txt</code>).
    * <p>
-   * 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
    * (<code>foo/../bar.txt</code> is same as <code>bar.txt</code>). It must
    * not be <code>null</code>.
+   * <p>
+   * 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.
-   * <br>
-   * If the parameter starts with <code>file:</code>, then absolute path is used, else relative path. Pattern
-   * is case-sensitive, except for file extension.
-   * <br>
+   * Predicate that gets the files which "path" matches a wildcard pattern.
+   * <p>
+   * The path is the path part of the {@link InputFile#uri()}. Pattern is case-sensitive, except for file extension.
+   * <p>
    * Supported wildcards are <code>&#42;</code> and <code>&#42;&#42;</code>, but not <code>?</code>.
    * <br>
    * Examples:
@@ -99,7 +100,6 @@ public interface FilePredicates {
    *   <li><code>&#42;&#42;/&#42;Foo&#42;.java</code> matches src/Foo.java, src/BarFoo.java, src/FooBar.java
    *   and src/BarFooBaz.java</li>
    *   <li><code>&#42;&#42;/&#42;FOO.JAVA</code> matches FOO.java and FOO.JAVA but not Foo.java</li>
-   *   <li><code>file:&#42;&#42;/src/&#42;Foo.java</code> matches /path/to/src/Foo.java on unix and c:\path\to\Foo.java on MSWindows</li>
    * </ul>
    */
   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)}
+   * <p>
+   * 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 {
    * <code>/path/to/module/src/main/java/com/Foo.java</code>.
    * <br>
    * 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();
 }