#3377: Correct Poco::Path::configHome() and dataHome() documentation for Windows

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 @@ public:
 		PATH_NATIVE,  /// The current platform's native style
 		PATH_GUESS    /// Guess the style by examining the path
 	};
-	
+
 	typedef std::vector<std::string> StringVec;
 
 	Path();
@@ -89,13 +89,13 @@ public:
 
 	~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 @@ public:
 
 	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 @@ public:
 		/// 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 @@ public:
 
 	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 @@ public:
 
 	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 @@ public:
 
 	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 @@ public:
 
 	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 @@ public:
 
 	static std::string current();
 		/// Returns the current working directory.
-		
+
 	static std::string home();
 		/// Returns the user's home directory.
 
@@ -300,13 +300,13 @@ public:
 		/// 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 @@ public:
 		/// 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 @@ public:
 		/// 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 @@ public:
 		/// 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)
 {