From 8bfeb520188c95b9843d75c8cfa6e061c9548782 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=BCnter=20Obiltschnig?= Date: Fri, 5 Nov 2021 14:26:59 +0100 Subject: [PATCH] #3377: Correct Poco::Path::configHome() and dataHome() documentation for Windows --- Foundation/include/Poco/Path.h | 96 +++++++++++++++++----------------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/Foundation/include/Poco/Path.h b/Foundation/include/Poco/Path.h index 30e465a5ab..033e2d31d3 100644 --- a/Foundation/include/Poco/Path.h +++ b/Foundation/include/Poco/Path.h @@ -26,7 +26,7 @@ namespace Poco { class Foundation_API Path - /// This class represents filesystem paths in a + /// This class represents filesystem paths in a /// platform-independent manner. /// Unix, Windows and OpenVMS all use a different /// syntax for filesystem paths. @@ -47,7 +47,7 @@ class Foundation_API Path PATH_NATIVE, /// The current platform's native style PATH_GUESS /// Guess the style by examining the path }; - + typedef std::vector StringVec; Path(); @@ -89,13 +89,13 @@ class Foundation_API Path ~Path(); /// Destroys the Path. - + Path& operator = (const Path& path); /// Assignment operator. Path& operator = (Path&& path) noexcept; /// Move assignment. - + Path& operator = (const std::string& path); /// Assigns a string containing a path in native format. @@ -107,22 +107,22 @@ class Foundation_API Path Path& assign(const std::string& path); /// Assigns a string containing a path in native format. - + Path& assign(const std::string& path, Style style); /// Assigns a string containing a path. Path& assign(const Path& path); /// Assigns the given path. - + Path& assign(const char* path); /// Assigns a string containing a path. std::string toString() const; /// Returns a string containing the path in native format. - + std::string toString(Style style) const; /// Returns a string containing the path in the given format. - + Path& parse(const std::string& path); /// Same as assign(). @@ -133,7 +133,7 @@ class Foundation_API Path /// Tries to interpret the given string as a path /// in native format. /// If the path is syntactically valid, assigns the - /// path and returns true. Otherwise leaves the + /// path and returns true. Otherwise leaves the /// object unchanged and returns false. bool tryParse(const std::string& path, Style style); @@ -162,18 +162,18 @@ class Foundation_API Path Path& makeParent(); /// Makes the path refer to its parent. - + Path& makeAbsolute(); /// Makes the path absolute if it is relative. /// The current working directory is taken as base directory. Path& makeAbsolute(const Path& base); /// Makes the path absolute if it is relative. - /// The given path is taken as base. + /// The given path is taken as base. Path& append(const Path& path); /// Appends the given path. - + Path& resolve(const Path& path); /// Resolves the given path against the current one. /// @@ -182,57 +182,57 @@ class Foundation_API Path bool isAbsolute() const; /// Returns true iff the path is absolute. - + bool isRelative() const; /// Returns true iff the path is relative. - + bool isDirectory() const; /// Returns true iff the path references a directory /// (the filename part is empty). - + bool isFile() const; /// Returns true iff the path references a file /// (the filename part is not empty). - + Path& setNode(const std::string& node); /// Sets the node name. /// Setting a non-empty node automatically makes /// the path an absolute one. - + const std::string& getNode() const; /// Returns the node name. - + Path& setDevice(const std::string& device); /// Sets the device name. /// Setting a non-empty device automatically makes /// the path an absolute one. - + const std::string& getDevice() const; /// Returns the device name. - + int depth() const; /// Returns the number of directories in the directory list. const std::string& directory(int n) const; /// Returns the n'th directory in the directory list. /// If n == depth(), returns the filename. - + const std::string& operator [] (int n) const; /// Returns the n'th directory in the directory list. /// If n == depth(), returns the filename. - + Path& pushDirectory(const std::string& dir); /// Adds a directory to the directory list. - + Path& popDirectory(); /// Removes the last directory from the directory list. - + Path& popFrontDirectory(); /// Removes the first directory from the directory list. - + Path& setFileName(const std::string& name); /// Sets the filename. - + const std::string& getFileName() const; /// Returns the filename. @@ -246,20 +246,20 @@ class Foundation_API Path Path& setExtension(const std::string& extension); /// Sets the filename extension. - + std::string getExtension() const; /// Returns the filename extension. - + const std::string& version() const; /// Returns the file version. VMS only. - + Path& clear(); /// Clears all components. Path parent() const; /// Returns a path referring to the path's /// directory. - + Path absolute() const; /// Returns an absolute variant of the path, /// taking the current working directory as base. @@ -276,12 +276,12 @@ class Foundation_API Path static char separator(); /// Returns the platform's path name separator, which separates - /// the components (names) in a path. + /// the components (names) in a path. /// - /// On Unix systems, this is the slash '/'. On Windows systems, + /// On Unix systems, this is the slash '/'. On Windows systems, /// this is the backslash '\'. On OpenVMS systems, this is the /// period '.'. - + static char pathSeparator(); /// Returns the platform's path separator, which separates /// single paths in a list of paths. @@ -292,7 +292,7 @@ class Foundation_API Path static std::string current(); /// Returns the current working directory. - + static std::string home(); /// Returns the user's home directory. @@ -300,13 +300,13 @@ class Foundation_API Path /// Returns the user's config directory. /// /// On Unix systems, this is the '~/.config/'. On Windows systems, - /// this is '%APPDATA%'. + /// this is '%APPDATA%' (typically C:\Users\user\AppData\Roaming). static std::string dataHome(); /// Returns the user's data directory. /// /// On Unix systems, this is the '~/.local/share/'. On Windows systems, - /// this is '%APPDATA%'. + /// this is '%LOCALAPPDATA%' (typically C:\Users\user\AppData\Local). static std::string tempHome(); /// Returns the user's temp directory. @@ -317,19 +317,19 @@ class Foundation_API Path /// Returns the user's cache directory. /// /// On Unix systems, this is the '~/.cache/'. On Windows systems, - /// this is '%APPDATA%'. + /// this is the same as tempHome(). static std::string temp(); /// Returns the temporary directory. - + static std::string config(); /// Returns the systemwide config directory. /// /// On Unix systems, this is the '/etc/'. - + static std::string null(); /// Returns the name of the null device. - + static std::string expand(const std::string& path); /// Expands all environment variables contained in the path. /// @@ -341,13 +341,13 @@ class Foundation_API Path /// system. On Unix, there is exactly one root, "/". /// On Windows, the roots are the drive letters. /// On OpenVMS, the roots are the mounted disks. - + static bool find(StringVec::const_iterator it, StringVec::const_iterator end, const std::string& name, Path& path); /// Searches the file with the given name in the locations (paths) specified /// by it and end. A relative path may be given in name. /// /// If the file is found in one of the locations, the complete - /// path of the file is stored in the path given as argument and true is returned. + /// path of the file is stored in the path given as argument and true is returned. /// Otherwise false is returned and the path argument remains unchanged. static bool find(const std::string& pathList, const std::string& name, Path& path); @@ -356,13 +356,13 @@ class Foundation_API Path /// path separator (see pathSeparator()). A relative path may be given in name. /// /// If the file is found in one of the locations, the complete - /// path of the file is stored in the path given as argument and true is returned. + /// path of the file is stored in the path given as argument and true is returned. /// Otherwise false is returned and the path argument remains unchanged. - + static std::string transcode(const std::string& path); - /// On Windows, this function converts a string (usually containing a path) + /// On Windows, this function converts a string (usually containing a path) /// encoded in UTF-8 into a string encoded in the current Windows code page. - /// + /// /// This function should be used for every string passed as a file name to /// a string stream or fopen(). /// @@ -396,7 +396,7 @@ inline bool Path::isAbsolute() const return _absolute; } - + inline bool Path::isRelative() const { return !_absolute; @@ -462,7 +462,7 @@ inline Path Path::forDirectory(const std::string& path) Path p; return p.parseDirectory(path); } - + inline Path Path::forDirectory(const std::string& path, Style style) {