Trying to make wxFileName docs readable again

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@54788 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/interface/wx/filename.h b/interface/wx/filename.h
index 3a8317ed0920ab52274a8defb5476c98f2fed04d..018eed690fab973aeb4a2208be4252d8e0f64d7f 100644 (file)
--- a/interface/wx/filename.h
+++ b/interface/wx/filename.h
@@ -58,6 +58,94 @@
         fname.Assign( user_input );
     @endcode
 
         fname.Assign( user_input );
     @endcode
 

+        These functions allow to examine and modify the individual directories
+        of the path:
+        
+        @li AppendDir()
+        @li InsertDir()
+        @li GetDirCount()
+        @li PrependDir()
+        @li RemoveDir()
+        @li RemoveLastDir()
+        
+        To change the components of the file name individually you can use the
+        following functions:
+        
+        @li GetExt()
+        @li GetName()
+        @li GetVolume()
+        @li HasExt()
+        @li HasName()
+        @li HasVolume()
+        @li SetExt()
+        @li ClearExt()
+        @li SetEmptyExt()
+        @li SetName()
+        @li SetVolume()
+        
+        You can initialize a wxFileName instance using one of the following functions:
+        
+        @li wxFilename()
+        @li Assign()
+        @li AssignCwd()
+        @li AssignDir()
+        @li AssignHomeDir()
+        @li DirName()
+        @li FileName()
+        
+        wxFileName currently supports the file names in the Unix, DOS/Windows, Mac OS
+        and VMS formats (Mac OS no longer being maintained as OS X uses the Unix notation).
+        Although these formats are quite different, wxFileName tries to treat them all
+        in the same generic way. It supposes that all file names consist of the following
+        parts: the volume (also known as drive under Windows or device under VMS), the
+        path which is a sequence of directory names separated by the 
+        @ref getpathseparators() "path separators" 
+        and the full filename itself which, in turn, is composed from the base file name
+        and the extension. All of the individual components of the file name may be empty
+        and, for example, the volume name is always empty under Unix, but if they are all
+        empty simultaneously, the filename object is considered to be in an invalid
+        state and IsOk() returns @false for it.
+        File names can be case-sensitive or not, the function IsCaseSensitive() allows to
+        determine this. The rules for determining whether the file name is absolute or
+        relative also depend on the file name format and the only portable way to answer
+        this question is to use IsAbsolute() or IsRelative() method. Note that on Windows, 
+        "X:" refers to the current working directory on drive X. Therefore, a wxFileName
+        instance constructed from for example "X:dir/file.ext" treats the portion beyond
+        drive separator as being relative to that directory. To ensure that the filename
+        is absolute, you may use MakeAbsolute(). There is also an inverse function
+        MakeRelativeTo() which undoes what Normalize(wxPATH_NORM_DOTS) does.
+        Other functions returning information about the file format provided by this
+        class are GetVolumeSeparator(), IsPathSeparator().
+
+        Before doing other tests, you should use IsOk() to verify that the filename
+        is well defined. If it is, FileExists() can be used to test whether a file
+        with such name exists and DirExists() can be used to test for directory existence.
+        File names should be compared using the SameAs() method or operator=(). For testing
+        basic access modes, you can use:
+        
+        @li IsDirWritable()
+        @li IsDirReadable()
+        @li IsFileWritable()
+        @li IsFileReadable()
+        @li IsFileExecutable()
+
+        These methods allow to work with the file creation, access and modification
+        times. Note that not all filesystems under all platforms implement these times
+        in the same way. For example, the access time under Windows has a resolution of
+        one day (so it is really the access date and not time). The access time may be
+        updated when the file is executed or not depending on the platform.
+        
+        @li GetModificationTime()
+        @li GetTimes()
+        @li SetTimes()
+        @li Touch()
+        
+        Other file system operations functions are:
+        
+        @li Mkdir()
+        @li Rmdir()
+
+

     @library{wxbase}
     @category{file}
 
     @library{wxbase}
     @category{file}
 


@@ -66,24 +154,37 @@
 class wxFileName
 {
 public:
 class wxFileName
 {
 public:

-    //@{

     /**
     /**

-        Constructor from a volume name, a directory name, base file name and extension.
+        Default constructor.

     */
     wxFileName();
     */
     wxFileName();

+    /**
+        Copy constructor.
+    */

     wxFileName(const wxFileName& filename);
     wxFileName(const wxFileName& filename);

+    /**
+        Constructor from a full file name including the path.
+    */

     wxFileName(const wxString& fullpath,
                wxPathFormat format = wxPATH_NATIVE);
     wxFileName(const wxString& fullpath,
                wxPathFormat format = wxPATH_NATIVE);

+    /**
+        Constructor a directory name and file name.
+    */

     wxFileName(const wxString& path, const wxString& name,
                wxPathFormat format = wxPATH_NATIVE);
     wxFileName(const wxString& path, const wxString& name,
                wxPathFormat format = wxPATH_NATIVE);

+    /**
+        Constructor from a directory name, base file name and extension.
+    */

     wxFileName(const wxString& path, const wxString& name,
                const wxString& ext,
                wxPathFormat format = wxPATH_NATIVE);
     wxFileName(const wxString& path, const wxString& name,
                const wxString& ext,
                wxPathFormat format = wxPATH_NATIVE);

+    /**
+        Constructor from a volume name, a directory name, base file name and extension.
+    */

     wxFileName(const wxString& volume, const wxString& path,
                const wxString& name,
                const wxString& ext,
                wxPathFormat format = wxPATH_NATIVE);
     wxFileName(const wxString& volume, const wxString& path,
                const wxString& name,
                const wxString& ext,
                wxPathFormat format = wxPATH_NATIVE);

-    //@}

 
     /**
         Appends a directory component to the path. This component should contain a
 
     /**
         Appends a directory component to the path. This component should contain a


@@ -93,28 +194,41 @@ public:
     */
     void AppendDir(const wxString& dir);
 
     */
     void AppendDir(const wxString& dir);
 

-    //@{

     /**
     /**

-        Creates the file name from various combinations of data.
+        Creates the file name from another filename object.

     */
     void Assign(const wxFileName& filepath);
     */
     void Assign(const wxFileName& filepath);

+    /**
+        Creates the file name from a full file name with a path.
+    */

     void Assign(const wxString& fullpath,
                 wxPathFormat format = wxPATH_NATIVE);
     void Assign(const wxString& fullpath,
                 wxPathFormat format = wxPATH_NATIVE);

+    /**
+        Creates the file name from volumne, path, name and extension.
+    */

     void Assign(const wxString& volume, const wxString& path,
                 const wxString& name,
                 const wxString& ext,
                 bool hasExt,
                 wxPathFormat format = wxPATH_NATIVE);
     void Assign(const wxString& volume, const wxString& path,
                 const wxString& name,
                 const wxString& ext,
                 bool hasExt,
                 wxPathFormat format = wxPATH_NATIVE);

+    /**
+        Creates the file name from volumne, path, name and extension.
+    */

     void Assign(const wxString& volume, const wxString& path,
                 const wxString& name,
                 const wxString& ext,
                 wxPathFormat format = wxPATH_NATIVE);
     void Assign(const wxString& volume, const wxString& path,
                 const wxString& name,
                 const wxString& ext,
                 wxPathFormat format = wxPATH_NATIVE);

+    /**
+        Creates the file name from file path and file name.
+    */

     void Assign(const wxString& path, const wxString& name,
                 wxPathFormat format = wxPATH_NATIVE);
     void Assign(const wxString& path, const wxString& name,
                 wxPathFormat format = wxPATH_NATIVE);

+    /**
+        Creates the file name from path, name and extension.
+    */

     void Assign(const wxString& path, const wxString& name,
                 const wxString& ext,
                 wxPathFormat format = wxPATH_NATIVE);
     void Assign(const wxString& path, const wxString& name,
                 const wxString& ext,
                 wxPathFormat format = wxPATH_NATIVE);

-    //@}

 
     /**
         Makes this object refer to the current working directory on the specified
 
     /**
         Makes this object refer to the current working directory on the specified


@@ -182,13 +296,15 @@ public:
     static wxString CreateTempFileName(const wxString& prefix,
                                        wxFile* fileTemp = NULL);
 
     static wxString CreateTempFileName(const wxString& prefix,
                                        wxFile* fileTemp = NULL);
 

-    //@{

     /**
         Returns @true if the directory with this name exists.
     */
     bool DirExists();
     /**
         Returns @true if the directory with this name exists.
     */
     bool DirExists();

+    
+    /**
+        Returns @true if the directory with this name exists.
+    */

     const static bool DirExists(const wxString& dir);
     const static bool DirExists(const wxString& dir);

-    //@}

 
     /**
         Returns the object corresponding to the directory with the given name.
 
     /**
         Returns the object corresponding to the directory with the given name.


@@ -198,127 +314,18 @@ public:
                               wxPathFormat format = wxPATH_NATIVE);
 
     /**
                               wxPathFormat format = wxPATH_NATIVE);
 
     /**

-        These functions allow to examine and modify the individual directories of the
-        path:
-        AppendDir()
-
-        InsertDir()
-
-        GetDirCount()
-        PrependDir()
-
-        RemoveDir()
-
-        RemoveLastDir()
-        To change the components of the file name individually you can use the
-        following functions:
-        GetExt()
-
-        GetName()
-
-        GetVolume()
-
-        HasExt()
-
-        HasName()
-
-        HasVolume()
-
-        SetExt()
-
-        ClearExt()
-
-        SetEmptyExt()
-
-        SetName()
-
-        SetVolume()
-    */
-
-
-    /**
-        You can initialize a wxFileName instance using one of the following functions:
-        @ref wxfilename() "wxFileName constructors"
-
-        Assign()
-
-        AssignCwd()
-
-        AssignDir()
-
-        AssignHomeDir()
-
-        @ref assigntempfilename() AssignHomeTempFileName
-
-        DirName()
-
-        FileName()
-
-        @ref operatorassign() "operator ="
-    */
-
-
-    /**
-        wxFileName currently supports the file names in the Unix, DOS/Windows, Mac OS
-        and VMS formats. Although these formats are quite different, wxFileName tries
-        to treat them all in the same generic way. It supposes that all file names
-        consist of the following parts: the volume (also known as drive under Windows
-        or device under VMS), the path which is a sequence of directory names separated
-        by the @ref getpathseparators() "path separators" and the full
-        filename itself which, in turn, is composed from the base file name and the
-        extension. All of the individual components of the file name may be empty and,
-        for example, the volume name is always empty under Unix, but if they are all
-        empty simultaneously, the filename object is considered to be in an invalid
-        state and IsOk() returns @false for it.
-        File names can be case-sensitive or not, the function
-        IsCaseSensitive() allows to determine this.
-        The rules for determining whether the file name is absolute or relative also
-        depend on the file name format and the only portable way to answer this
-        question is to use IsAbsolute() or
-        IsRelative() method. Note that on Windows, "X:"
-        refers to the current working directory on drive X. Therefore, a wxFileName
-        instance constructed from for example "X:dir/file.ext" treats the portion
-        beyond drive separator as being relative to that directory.
-        To ensure that the filename is absolute, you may use
-        MakeAbsolute(). There is also an inverse
-        function MakeRelativeTo() which undoes
-        what @ref normalize() Normalize(wxPATH_NORM_DOTS) does.
-        Other functions returning information about the file format provided by this
-        class are GetVolumeSeparator(),
-        IsPathSeparator().
-    */
-
-
-    /**
-        Before doing other tests, you should use IsOk() to
-        verify that the filename is well defined. If it is,
-        FileExists() can be used to test whether a file
-        with such name exists and DirExists() can be used
-        to test for directory existence.
-        File names should be compared using SameAs() method
-        or @ref operatorequal() "operator ==".
-        For testing basic access modes, you can use:
-        IsDirWritable()
-
-        IsDirReadable()
-
-        IsFileWritable()
-
-        IsFileReadable()
+        Returns @true if the file with this name exists.

 
 

-        IsFileExecutable()
+        @see DirExists()

     */
     */

-
-
-    //@{
+    bool FileExists();
+    

     /**
         Returns @true if the file with this name exists.
 
         @see DirExists()
     */
     /**
         Returns @true if the file with this name exists.
 
         @see DirExists()
     */

-    bool FileExists();

     const static bool FileExists(const wxString& file);
     const static bool FileExists(const wxString& file);

-    //@}

 
     /**
         Returns the file name object corresponding to the given @e file. This
 
     /**
         Returns the file name object corresponding to the given @e file. This


@@ -424,15 +431,13 @@ public:
 
         @b wxPATH_GET_VOLUME
 
 
         @b wxPATH_GET_VOLUME
 

-        Return the path with the volume (does
-        nothing for the filename formats without volumes), otherwise the path without
-        volume part is returned.
+        Return the path with the volume (does nothing for the filename formats without
+        volumes), otherwise the path without volume part is returned.

 
         @b wxPATH_GET_SEPARATOR
 
 
         @b wxPATH_GET_SEPARATOR
 

-        Return the path with the trailing
-        separator, if this flag is not given there will be no separator at the end of
-        the path.
+        Return the path with the trailing separator, if this flag is not given there
+        will be no separator at the end of the path.

     */
     wxString GetPath(int flags = wxPATH_GET_VOLUME,
                      wxPathFormat format = wxPATH_NATIVE) const;
     */
     wxString GetPath(int flags = wxPATH_GET_VOLUME,
                      wxPathFormat format = wxPATH_NATIVE) const;


@@ -477,17 +482,18 @@ public:
     */
     wxString GetShortPath() const;
 
     */
     wxString GetShortPath() const;
 

-    //@{

     /**
     /**

-        Returns the size of this file (first form) or the size of the given file
-        (second form).
-        If the file does not exist or its size could not be read (because e.g. the file
-        is locked
-        by another process) the returned value is @c wxInvalidSize.
+        Returns the size of the file If the file does not exist or its size could
+        not be read (because e.g. the file is locked by another process) the returned
+        value is @c wxInvalidSize.

     */
     wxULongLong GetSize();
     */
     wxULongLong GetSize();

+    /**
+        Returns the size of the file If the file does not exist or its size could
+        not be read (because e.g. the file is locked by another process) the returned
+        value is @c wxInvalidSize.
+    */

     const static wxULongLong GetSize(const wxString& filename);
     const static wxULongLong GetSize(const wxString& filename);

-    //@}

 
     /**
         Returns the directory used for temporary files.
 
     /**
         Returns the directory used for temporary files.


@@ -690,8 +696,23 @@ public:
     bool MakeRelativeTo(const wxString& pathBase = wxEmptyString,
                         wxPathFormat format = wxPATH_NATIVE);
 
     bool MakeRelativeTo(const wxString& pathBase = wxEmptyString,
                         wxPathFormat format = wxPATH_NATIVE);
 

-    //@{

     /**
     /**

+        Creates a directory.
+    
+        @param parm
+            the permissions for the newly created directory
+        @param flags
+            if the flags contain wxPATH_MKDIR_FULL flag,
+            try to create each directory in the path and also don't return an error
+            if the target directory already exists.
+
+        @return Returns @true if the directory was successfully created, @false
+                 otherwise.
+    */
+    bool Mkdir(int perm = 0777, int flags = 0);
+    /**
+        Creates a directory.
+        

         @param dir
             the directory to create
         @param parm
         @param dir
             the directory to create
         @param parm


@@ -704,10 +725,8 @@ public:
         @return Returns @true if the directory was successfully created, @false
                  otherwise.
     */
         @return Returns @true if the directory was successfully created, @false
                  otherwise.
     */

-    bool Mkdir(int perm = 0777, int flags = 0);

     static bool Mkdir(const wxString& dir, int perm = 0777,
                       int flags = 0);
     static bool Mkdir(const wxString& dir, int perm = 0777,
                       int flags = 0);

-    //@}

 
     /**
         Normalize the path. With the default flags value, the path will be
 
     /**
         Normalize the path. With the default flags value, the path will be


@@ -717,96 +736,19 @@ public:
         @param flags
             The kind of normalization to do with the file name. It can be
             any or-combination of the following constants:
         @param flags
             The kind of normalization to do with the file name. It can be
             any or-combination of the following constants:

-
-
-
-
-
-
-            wxPATH_NORM_ENV_VARS
-
-
-
-
-            replace env vars with their values
-
-
-
-
-
-            wxPATH_NORM_DOTS
-
-
-
-
-            squeeze all .. and . when possible; if there are too many .. and thus they
-        cannot be all removed, @false will be returned
-
-
-
-
-
-            wxPATH_NORM_CASE
-
-
-
-
-            if filesystem is case insensitive, transform to lower case
-
-
-
-
-
-            wxPATH_NORM_ABSOLUTE
-
-
-
-
-            make the path absolute prepending cwd
-
-
-
-
-
-            wxPATH_NORM_LONG
-
-
-
-
-            make the path the long form
-
-
-
-
-
-            wxPATH_NORM_SHORTCUT
-
-
-
-
-            resolve if it is a shortcut (Windows only)
-
-
-
-
-
-            wxPATH_NORM_TILDE
-
-
-
-
-            replace ~ and ~user (Unix only)
-
-
-
-
-
-            wxPATH_NORM_ALL
-
-
-
-
-            all of previous flags except wxPATH_NORM_CASE
+            
+            - wxPATH_NORM_ENV_VARS:  replace env vars with their values
+            - wxPATH_NORM_DOTS:  squeeze all .. and . when possible; if
+               there are too many .. and thus they cannot be all removed, 
+               @false will be returned
+            - wxPATH_NORM_CASE: if filesystem is case insensitive, transform
+               to lower case
+            - wxPATH_NORM_ABSOLUTE: make the path absolute prepending cwd
+            - wxPATH_NORM_LONG: make the path the long form
+            - wxPATH_NORM_SHORTCUT: resolve if it is a shortcut (Windows only)
+            - wxPATH_NORM_TILDE: replace ~ and ~user (Unix only)
+            - wxPATH_NORM_ALL: all of previous flags except wxPATH_NORM_CASE
+            

         @param cwd
             If not empty, this directory will be used instead of current
             working directory in normalization (see wxPATH_NORM_ABSOLUTE).
         @param cwd
             If not empty, this directory will be used instead of current
             working directory in normalization (see wxPATH_NORM_ABSOLUTE).


@@ -819,25 +761,6 @@ public:
                    const wxString& cwd = wxEmptyString,
                    wxPathFormat format = wxPATH_NATIVE);
 
                    const wxString& cwd = wxEmptyString,
                    wxPathFormat format = wxPATH_NATIVE);
 

-    /**
-        These methods allow to work with the file creation, access and modification
-        times. Note that not all filesystems under all platforms implement these times
-        in the same way. For example, the access time under Windows has a resolution of
-        one day (so it is really the access date and not time). The access time may be
-        updated when the file is executed or not depending on the platform.
-        GetModificationTime()
-
-        GetTimes()
-
-        SetTimes()
-
-        Touch()
-        Other file system operations functions are:
-        Mkdir()
-
-        Rmdir()
-    */
-

 
     /**
         Prepends a directory to the file path. Please see
 
     /**
         Prepends a directory to the file path. Please see