From 23f59fd99cb8cf41d21d50071c60abc21df60603 Mon Sep 17 00:00:00 2001
From: jules <jules@rawmaterialsoftware.com>
Date: Mon, 8 Jul 2013 17:59:37 +0100
Subject: [PATCH] Improved some documentation in the File class.

---
 modules/juce_core/files/juce_File.h | 32 +++++++++++++++--------------
 1 file changed, 17 insertions(+), 15 deletions(-)

diff --git a/modules/juce_core/files/juce_File.h b/modules/juce_core/files/juce_File.h
index 880884629a..6164f65e34 100644
--- a/modules/juce_core/files/juce_File.h
+++ b/modules/juce_core/files/juce_File.h
@@ -75,10 +75,10 @@ public:
         On the Mac/Linux, the path can include "~" notation for referring to
         user home directories.
     */
-    File (const String& path);
+    File (const String& absolutePath);
 
     /** Creates a copy of another file object. */
-    File (const File& other);
+    File (const File&);
 
     /** Destructor. */
     ~File() noexcept  {}
@@ -93,14 +93,14 @@ public:
         On the Mac/Linux, the path can include "~" notation for referring to
         user home directories.
     */
-    File& operator= (const String& newFilePath);
+    File& operator= (const String& newAbsolutePath);
 
     /** Copies from another file object. */
     File& operator= (const File& otherFile);
 
    #if JUCE_COMPILER_SUPPORTS_MOVE_SEMANTICS
-    File (File&& otherFile) noexcept;
-    File& operator= (File&& otherFile) noexcept;
+    File (File&&) noexcept;
+    File& operator= (File&&) noexcept;
    #endif
 
     //==============================================================================
@@ -250,12 +250,13 @@ public:
     int64 hashCode64() const;
 
     //==============================================================================
-    /** Returns a file based on a relative path.
+    /** Returns a file that represents a relative (or absolute) sub-path of the current one.
 
         This will find a child file or directory of the current object.
 
         e.g.
             File ("/moose/fish").getChildFile ("foo.txt") will produce "/moose/fish/foo.txt".
+            File ("/moose/fish").getChildFile ("haddock/foo.txt") will produce "/moose/fish/haddock/foo.txt".
             File ("/moose/fish").getChildFile ("../foo.txt") will produce "/moose/foo.txt".
 
         If the string is actually an absolute path, it will be treated as such, e.g.
@@ -263,7 +264,7 @@ public:
 
         @see getSiblingFile, getParentDirectory, getRelativePathFrom, isAChildOf
     */
-    File getChildFile (String relativePath) const;
+    File getChildFile (String relativeOrAbsolutePath) const;
 
     /** Returns a file which is in the same directory as this one.
 
@@ -326,13 +327,13 @@ public:
 
     //==============================================================================
     /** Compares the pathnames for two files. */
-    bool operator== (const File& otherFile) const;
+    bool operator== (const File&) const;
     /** Compares the pathnames for two files. */
-    bool operator!= (const File& otherFile) const;
+    bool operator!= (const File&) const;
     /** Compares the pathnames for two files. */
-    bool operator< (const File& otherFile) const;
+    bool operator< (const File&) const;
     /** Compares the pathnames for two files. */
-    bool operator> (const File& otherFile) const;
+    bool operator> (const File&) const;
 
     //==============================================================================
     /** Checks whether a file can be created or written to.
@@ -883,19 +884,20 @@ public:
     static const String separatorString;
 
     //==============================================================================
-    /** Removes illegal characters from a filename.
+    /** Returns a version of a filename with any illegal characters removed.
 
         This will return a copy of the given string after removing characters
         that are not allowed in a legal filename, and possibly shortening the
         string if it's too long.
 
-        Because this will remove slashes, don't use it on an absolute pathname.
+        Because this will remove slashes, don't use it on an absolute pathname - use
+        createLegalPathName() for that.
 
         @see createLegalPathName
     */
     static String createLegalFileName (const String& fileNameToFix);
 
-    /** Removes illegal characters from a pathname.
+    /** Returns a version of a path with any illegal characters removed.
 
         Similar to createLegalFileName(), but this won't remove slashes, so can
         be used on a complete pathname.
@@ -915,7 +917,7 @@ public:
 
         Best to avoid this unless you really know what you're doing.
     */
-    static File createFileWithoutCheckingPath (const String& path) noexcept;
+    static File createFileWithoutCheckingPath (const String& absolutePath) noexcept;
 
     /** Adds a separator character to the end of a path if it doesn't already have one. */
     static String addTrailingSeparator (const String& path);