[vcs] FilePath: fix and add some javadocs + mark a method as @NotNull

platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java

@@ -42,7 +42,7 @@ public interface FilePath {
   VirtualFile getVirtualFileParent();
 
   /**
-   * @return the {@link java.io.File} that corresponds to the path. The path might be non-existent or not local.
+   * @return the {@link File} that corresponds to the path. The path might be non-existent or not local.
    * @see #isNonLocal()
    */
   @NotNull
@@ -54,10 +54,16 @@ public interface FilePath {
   @NotNull
   String getName();
 
+  /**
+   * @return the path to the file in the format suitable for displaying in the UI,
+   * e.g. for local file it is the path to this file with system separators.
+   */
+  @NotNull
   String getPresentableUrl();
 
   /**
-   * @deprecated to remove in IDEA 16. Use {@link com.intellij.openapi.fileEditor.FileDocumentManager#getDocument(VirtualFile)}.
+   * @deprecated to remove in IDEA 16.
+   * Use {@link com.intellij.openapi.fileEditor.FileDocumentManager#getDocument(VirtualFile)} directly.
    */
   @Deprecated
   @Nullable
@@ -67,16 +73,13 @@ public interface FilePath {
   Charset getCharset();
 
   /**
-   * Get character set, considering the project defaults and a virtual file
-   *
-   * @param project the project which settings will be consulted
-   * @return the character set of the file
+   * @return the character set, considering the project settings and the virtual file corresponding to this FilePath (if it exists).
    */
   @NotNull
   Charset getCharset(@Nullable Project project);
 
   /**
-   * @return the type of the file
+   * @return the type of the file.
    */
   @NotNull
   FileType getFileType();
@@ -89,11 +92,15 @@ public interface FilePath {
   void refresh();
 
   /**
-   * @deprecated to remove in IDEA 16. Use {@code com.intellij.openapi.vfs.LocalFileSystem#refreshAndFindFileByPath} instead.
+   * @deprecated to remove in IDEA 16.
+   * Use {@code com.intellij.openapi.vfs.LocalFileSystem#refreshAndFindFileByPath} instead.
    */
   @Deprecated
   void hardRefresh();
 
+  /**
+   * @return the path to the file represented by this file path in the system-independent format.
+   */
   @NotNull
   String getPath();
 
@@ -112,7 +119,7 @@ public interface FilePath {
   boolean isUnder(@NotNull FilePath parent, boolean strict);
 
   /**
-   * @return the parent path or null if there are no parent
+   * @return the parent path or null if there is no parent of this file.
    */
   @Nullable
   FilePath getParentPath();

platform/vcs-impl/src/com/intellij/openapi/vcs/FilePathImpl.java

@@ -119,6 +119,7 @@ public class FilePathImpl implements FilePath {
     return PathUtil.getFileName(myPath);
   }
 
+  @NotNull
   @Override
   public String getPresentableUrl() {
     return FileUtil.toSystemDependentName(myPath);

platform/vcs-impl/src/com/intellij/openapi/vcs/RemoteFilePath.java

@@ -68,6 +68,7 @@ public class RemoteFilePath implements FilePath {
     return PathUtil.getFileName(myPath);
   }
 
+  @NotNull
   @Override
   public String getPresentableUrl() {
     return getPath();