some javadocs

platform/core-api/src/com/intellij/openapi/fileEditor/FileDocumentManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2000-2014 JetBrains s.r.o.
+ * Copyright 2000-2015 JetBrains s.r.o.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,27 +23,52 @@ import com.intellij.openapi.vfs.VirtualFile;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Tracks the correspondence between {@link VirtualFile} instances and corresponding {@link Document} instances.
+ * Manages the saving of changes to disk.
+ */
 public abstract class FileDocumentManager implements SavingRequestor {
   @NotNull
   public static FileDocumentManager getInstance() {
     return ApplicationManager.getApplication().getComponent(FileDocumentManager.class);
   }
 
+  /**
+   * Returns the document for the specified virtual file.
+   * @param file the file for which the document is requested.
+   * @return the document, or null if the file represents a directory, or is binary without an associated decompiler,
+   * or is too large.
+   */
   @Nullable
   public abstract Document getDocument(@NotNull VirtualFile file);
 
+  /**
+   * Returns the document for the specified file which has already been loaded into memory.
+   *
+   * @param file the file for which the document is requested.
+   * @return the document, or null if the specified virtual file hasn't been loaded into memory.
+   */
   @Nullable
   public abstract Document getCachedDocument(@NotNull VirtualFile file);
 
+  /**
+   * Returns the virtual file corresponding to the specified document.
+   *
+   * @param document the document for which the virtual file is requested.
+   * @return the file, or null if the document wasn't created from a virtual file.
+   */
   @Nullable
   public abstract VirtualFile getFile(@NotNull Document document);
 
   /**
-   * This operation can modify documents that will be saved (due to 'Trip trailing spaces on Save' functionality).
+   * Saves all unsaved documents to disk. This operation can modify documents that will be saved
+   * (due to 'Strip trailing spaces on Save' functionality).
    */
   public abstract void saveAllDocuments();
+
   /**
-   * This operation can modify the document (due to 'Trip trailing spaces on Save' functionality).
+   * Saves the specified document to disk. This operation can modify the document (due to 'Strip
+   * trailing spaces on Save' functionality).
    */
   public abstract void saveDocument(@NotNull Document document);
 
@@ -52,12 +77,35 @@ public abstract class FileDocumentManager implements SavingRequestor {
    * @param document the document to save.
    */
   public abstract void saveDocumentAsIs(@NotNull Document document);
-  
+
+  /**
+   * Returns the ist of all documents that have unsaved changes.
+   * @return the documents that have unsaved changes.
+   */
   @NotNull
   public abstract Document[] getUnsavedDocuments();
+
+  /**
+   * Checks if the document has unsaved changes.
+   *
+   * @param document the document to check.
+   * @return true if the document has unsaved changes, false otherwise.
+   */
   public abstract boolean isDocumentUnsaved(@NotNull Document document);
+
+  /**
+   * Checks if the document corresponding to the specified file has unsaved changes.
+   *
+   * @param file the file to check.
+   * @return true if the file has unsaved changes, false otherwise.
+   */
   public abstract boolean isFileModified(@NotNull VirtualFile file);
 
+  /**
+   * Discards unsaved changes for the specified document and reloads it from disk.
+   *
+   * @param document the document to reload.
+   */
   public abstract void reloadFromDisk(@NotNull Document document);
 
   @NotNull
@@ -77,5 +125,10 @@ public abstract class FileDocumentManager implements SavingRequestor {
     return getInstance().requestWriting(document, project);
   }
 
+  /**
+   * Discards unsaved changes for the specified files.
+   *
+   * @param files the files to discard the changes for.
+   */
   public abstract void reloadFiles(@NotNull VirtualFile... files);
 }

platform/core-api/src/com/intellij/psi/PsiDocumentManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2000-2009 JetBrains s.r.o.
+ * Copyright 2000-2015 JetBrains s.r.o.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,6 +29,13 @@ import java.util.EventListener;
  * Manages the relationship between documents and PSI trees.
  */
 public abstract class PsiDocumentManager {
+  /**
+   * Checks if the PSI tree for the specified document is up to date (its state reflects the latest changes made
+   * to the document content).
+   *
+   * @param document the document to check.
+   * @return true if the PSI tree for the document is up to date, false otherwise.
+   */
   public abstract boolean isCommitted(@NotNull Document document);
 
   /**
@@ -206,8 +213,22 @@ public abstract class PsiDocumentManager {
    */
   public abstract void removeListener(@NotNull Listener listener);
 
+  /**
+   * Checks if the PSI tree corresponding to the specified document has been modified and the changes have not
+   * yet been applied to the document. Documents in that state cannot be modified directly, because such changes
+   * would conflict with the pending PSI changes. Changes made through PSI are always applied in the end of a write action,
+   * and can be applied in the middle of a write action by calling {@link #doPostponedOperationsAndUnblockDocument}.
+   *
+   * @param doc the document to check.
+   * @return true if the corresponding PSI has changes that haven't been applied to the document.
+   */
   public abstract boolean isDocumentBlockedByPsi(@NotNull Document doc);
 
+  /**
+   * Applies pending changes made through the PSI to the specified document.
+   *
+   * @param doc the document to apply the changes to.
+   */
   public abstract void doPostponedOperationsAndUnblockDocument(@NotNull Document doc);
 
   /**

platform/core-api/src/com/intellij/psi/PsiFile.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2000-2012 JetBrains s.r.o.
+ * Copyright 2000-2015 JetBrains s.r.o.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,7 +19,6 @@ import com.intellij.lang.FileASTNode;
 import com.intellij.openapi.fileTypes.FileType;
 import com.intellij.openapi.vfs.VirtualFile;
 import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
 
 /**
  * A PSI element representing a file.
@@ -101,5 +100,9 @@ public interface PsiFile extends PsiFileSystemItem {
   @Override
   FileASTNode getNode();
 
+  /**
+   * Called by the PSI framework when the contents of the file changes. Can be used to invalidate
+   * file-level caches. If you override this method, you <b>must</b> call the base class implementation.
+   */
   void subtreeChanged();
 }