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]
This commit is contained in:
rdb 2023-05-08 10:32:50 +02:00
parent cc74efa79a
commit c958919037
3 changed files with 28 additions and 13 deletions

View File

@ -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 {

View File

@ -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:

View File

@ -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 {