From 4171f63d19f7d87bb530749d5c15fa6ec2c487e7 Mon Sep 17 00:00:00 2001 From: Dmitry Jemerov Date: Tue, 24 Feb 2015 18:07:58 +0100 Subject: [PATCH] some javadocs --- .../fileEditor/FileDocumentManager.java | 61 +++++++++++++++++-- .../com/intellij/psi/PsiDocumentManager.java | 23 ++++++- .../src/com/intellij/psi/PsiFile.java | 7 ++- 3 files changed, 84 insertions(+), 7 deletions(-) diff --git a/platform/core-api/src/com/intellij/openapi/fileEditor/FileDocumentManager.java b/platform/core-api/src/com/intellij/openapi/fileEditor/FileDocumentManager.java index 2bd3099dbf65..3e71eb849bc5 100644 --- a/platform/core-api/src/com/intellij/openapi/fileEditor/FileDocumentManager.java +++ b/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); } diff --git a/platform/core-api/src/com/intellij/psi/PsiDocumentManager.java b/platform/core-api/src/com/intellij/psi/PsiDocumentManager.java index d05b11e47de1..36299685bc51 100644 --- a/platform/core-api/src/com/intellij/psi/PsiDocumentManager.java +++ b/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); /** diff --git a/platform/core-api/src/com/intellij/psi/PsiFile.java b/platform/core-api/src/com/intellij/psi/PsiFile.java index 4a4cf92c965e..3f052ae59243 100644 --- a/platform/core-api/src/com/intellij/psi/PsiFile.java +++ b/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 must call the base class implementation. + */ void subtreeChanged(); }