From d438f1966cf670ea757e73419474d6a120475d0b Mon Sep 17 00:00:00 2001
From: peter <peter@jetbrains.com>
Date: Mon, 16 Jun 2014 20:38:52 +0200
Subject: [PATCH] reflect VirtualFile non-uniqueness in javadoc

---
 .../src/com/intellij/openapi/vfs/VirtualFile.java        | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java b/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java
index 0725d7a1ea0e..e4c3e5c502f5 100644
--- a/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java
+++ b/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java
@@ -31,9 +31,12 @@ import java.io.OutputStream;
 import java.nio.charset.Charset;
 
 /**
- * Represents a file in <code>{@link VirtualFileSystem}</code>. A particular file is represented by the same
- * <code>VirtualFile</code> instance for the entire lifetime of the IntelliJ IDEA process, unless the file
- * is deleted, in which case {@link #isValid()} for the instance will return <code>false</code>.
+ * Represents a file in <code>{@link VirtualFileSystem}</code>. A particular file is represented by equal
+ * <code>VirtualFile</code> instances for the entire lifetime of the IntelliJ IDEA process, unless the file
+ * is deleted, in which case {@link #isValid()} will return <code>false</code>.
+ * <p/>
+ * VirtualFile instances are created on request, so there can be several instances corresponding to the same file.
+ * All of them are equal, have the same hashCode and use shared storage for all related data, including user data (see {@link com.intellij.openapi.util.UserDataHolder}).
  * <p/>
  * If an in-memory implementation of VirtualFile is required, {@link com.intellij.testFramework.LightVirtualFile}
  * can be used.