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

@@ -1259,9 +1259,12 @@ to_os_long_name() const {
 }
 
 /**
- * Returns true if the filename exists on the disk, false otherwise.  If the
+ * Returns true if the filename exists on the physical disk, false otherwise.
- * type is indicated to be executable, this also tests that the file has
+ * 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.
+ * Returns true if the filename exists on the physical disk and is the name of
- * not a directory or device), false otherwise.
+ * 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
+ * Returns true if the filename exists on the physical disk and is either a
- * file that can be written to, or false otherwise.
+ * 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
+ * Returns true if the filename exists on the physical disk and is a directory
- * otherwise.
+ * 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 {

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:

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
+ * Convenience function; returns true if the named file exists as a directory in
- * directory.
+ * 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
+ * Convenience function; returns true if the named file exists as a regular file
- * regular file.
+ * in the virtual file system hierarchy.
  */
 INLINE bool VirtualFileSystem::
 is_regular_file(const Filename &filename) const {