From c958919037d80455e6b64bbb62b1bb2ace97a020 Mon Sep 17 00:00:00 2001
From: rdb <git@rdb.name>
Date: Mon, 8 May 2023 10:32:50 +0200
Subject: [PATCH] Make API documentation for Filename and VirtualFileSystem
 clearer

Mention specifically that Filename methods act on the physical disk whereas VirtualFileSystem methods act on the VFS

Fixes #1493

[skip ci]
---
 dtool/src/dtoolutil/filename.cxx      | 25 +++++++++++++++++--------
 dtool/src/dtoolutil/filename.h        |  5 +++++
 panda/src/express/virtualFileSystem.I | 11 ++++++-----
 3 files changed, 28 insertions(+), 13 deletions(-)

diff --git a/dtool/src/dtoolutil/filename.cxx b/dtool/src/dtoolutil/filename.cxx
index da5657dd9d..7d3ce1693f 100644
--- a/dtool/src/dtoolutil/filename.cxx
+++ b/dtool/src/dtoolutil/filename.cxx
@@ -1259,9 +1259,12 @@ to_os_long_name() const {
 }
 
 /**
- * Returns true if the filename exists on the disk, false otherwise.  If the
- * type is indicated to be executable, this also tests that the file has
+ * Returns true if the filename exists on the physical disk, false otherwise.
+ * If the type is indicated to be executable, this also tests that the file has
  * execute permission.
+ *
+ * @see VirtualFileSystem::exists() for checking whether the filename exists in
+ * the virtual file system.
  */
 bool Filename::
 exists() const {
@@ -1290,8 +1293,11 @@ exists() const {
 }
 
 /**
- * Returns true if the filename exists and is the name of a regular file (i.e.
- * not a directory or device), false otherwise.
+ * Returns true if the filename exists on the physical disk and is the name of
+ * a regular file (i.e. not a directory or device), false otherwise.
+ *
+ * @see VirtualFileSystem::is_regular_file() for checking whether the filename
+ * exists and is a regular file in the virtual file system.
  */
 bool Filename::
 is_regular_file() const {
@@ -1320,8 +1326,8 @@ is_regular_file() const {
 }
 
 /**
- * Returns true if the filename exists and is either a directory or a regular
- * file that can be written to, or false otherwise.
+ * Returns true if the filename exists on the physical disk and is either a
+ * directory or a regular file that can be written to, or false otherwise.
  */
 bool Filename::
 is_writable() const {
@@ -1352,8 +1358,11 @@ is_writable() const {
 }
 
 /**
- * Returns true if the filename exists and is a directory name, false
- * otherwise.
+ * Returns true if the filename exists on the physical disk and is a directory
+ * name, false otherwise.
+ *
+ * @see VirtualFileSystem::is_directory() for checking whether the filename
+ * exists as a directory in the virtual file system.
  */
 bool Filename::
 is_directory() const {
diff --git a/dtool/src/dtoolutil/filename.h b/dtool/src/dtoolutil/filename.h
index 99d94af5a6..35d18044f1 100644
--- a/dtool/src/dtoolutil/filename.h
+++ b/dtool/src/dtoolutil/filename.h
@@ -35,6 +35,11 @@ class DSearchPath;
  * convention, and it knows how to perform basic OS-specific I/O, like testing
  * for file existence and searching a searchpath, as well as the best way to
  * open an fstream for reading or writing.
+ *
+ * Note that the methods of Filename that interact with the filesystem (such
+ * as exists(), open_read(), etc.) directly interface with the operating system
+ * and are not aware of Panda's virtual file system.  To interact with the VFS,
+ * use the methods on VirtualFileSystem instead.
  */
 class EXPCL_DTOOL_DTOOLUTIL Filename {
 PUBLISHED:
diff --git a/panda/src/express/virtualFileSystem.I b/panda/src/express/virtualFileSystem.I
index b74b9edbee..713b992147 100644
--- a/panda/src/express/virtualFileSystem.I
+++ b/panda/src/express/virtualFileSystem.I
@@ -12,7 +12,8 @@
  */
 
 /**
- * Convenience function; returns true if the named file exists.
+ * Convenience function; returns true if the named file exists in the virtual
+ * file system hierarchy.
  */
 INLINE bool VirtualFileSystem::
 exists(const Filename &filename) const {
@@ -20,8 +21,8 @@ exists(const Filename &filename) const {
 }
 
 /**
- * Convenience function; returns true if the named file exists and is a
- * directory.
+ * Convenience function; returns true if the named file exists as a directory in
+ * the virtual file system hierarchy.
  */
 INLINE bool VirtualFileSystem::
 is_directory(const Filename &filename) const {
@@ -30,8 +31,8 @@ is_directory(const Filename &filename) const {
 }
 
 /**
- * Convenience function; returns true if the named file exists and is a
- * regular file.
+ * Convenience function; returns true if the named file exists as a regular file
+ * in the virtual file system hierarchy.
  */
 INLINE bool VirtualFileSystem::
 is_regular_file(const Filename &filename) const {