Removed docs for old clipboard functions, and reviewed/fixed atomic ops, file & directory, and environment function categories.

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

docs/doxygen/groups/funcmacro_atomic.h

@@ -14,17 +14,15 @@
 When using multi-threaded applications, it is often required to access or
 modify memory which is shared between threads. Atomic integer and pointer
 operations are an efficient way to handle this issue (another, less efficient,
-way is to use a mutex or critical section). A native implementation exists for
+way is to use a wxMutex or wxCriticalSection). A native implementation exists
-Windows, Linux, Solaris and Mac OS X, for other OS, a wxCriticalSection is used
+for Windows, Linux, Solaris and Mac OS X; for others, a wxCriticalSection is
-to protect the data.
+used to protect the data.
 
-One particular application is reference counting (used by so-called smart
+One particular application is reference counting (used by so-called
-pointers).
+@ref group_class_smartpointers "smart pointers").
 
 You should define your variable with the type wxAtomicInt in order to apply
 atomic operations to it.
 
-@header{wx/atomic.h}
-
 */
 

docs/doxygen/groups/funcmacro_clipboard.h

@@ -1,21 +0,0 @@
-/////////////////////////////////////////////////////////////////////////////
-// Name:        funcmacro_clipboard.h
-// Purpose:     Clipboard function and macro group docs
-// Author:      wxWidgets team
-// RCS-ID:      $Id: funcmacro_gdi.h 52454 2008-03-12 19:08:48Z BP $
-// Licence:     wxWindows license
-/////////////////////////////////////////////////////////////////////////////
-
-/**
-
-@defgroup group_funcmacro_clipboard Clipboard
-@ingroup group_funcmacro
-
-@warning These functions are deprecated, use the wxClipboard class instead.
-
-These clipboard functions are implemented for Windows only. 
-
-@header{wx/clipbrd.h}
-
-*/
-

docs/doxygen/groups/funcmacro_env.h

@@ -11,11 +11,9 @@
 @defgroup group_funcmacro_env Environment
 @ingroup group_funcmacro
 
-The functions in this section allow to access (get) or change value of
+These functions allow access to get or change the values of environment
-environment variables in a portable way. They are currently implemented under
+variables in a portable way. They are currently implemented under Win32 and
-Win32 and POSIX-like systems (Unix).
+POSIX-like systems (Unix).
-
-@header{wx/utils.h}
 
 */
 

docs/doxygen/groups/funcmacro_file.h

@@ -11,9 +11,10 @@
 @defgroup group_funcmacro_file Files and Directories
 @ingroup group_funcmacro
 
-@header{wx/filefn.h}
+These functions provide a platform-independent API for common file and
+directory functionality.
 
-@sa wxPathList, wxDir, wxFile, wxFileName
+@see wxPathList, wxDir, wxFile, wxFileName
 
 */
 

interface/atomic.h

@@ -16,14 +16,19 @@
 
 /**
     This function increments @a value in an atomic manner.
+
+    @header{wx/atomic.h}
 */
 void wxAtomicInc(wxAtomicInt& value);
 
 /**
-    This function decrements value in an atomic manner.
+    This function decrements value in an atomic manner. Returns 0 if value is 0
-    Returns 0 if value is 0 after decrementation or any non-zero value
+    after decrementation or any non-zero value (not necessarily equal to the
-    (not necessarily equal to the value of the variable) otherwise.
+    value of the variable) otherwise.
+
+    @header{wx/atomic.h}
 */
 wxInt32 wxAtomicDec(wxAtomicInt& value);
 
 //@}
+

interface/clipboard.h

@@ -1,76 +0,0 @@
-/////////////////////////////////////////////////////////////////////////////
-// Name:        clipboard.h
-// Purpose:     interface of global functions
-// Author:      wxWidgets team
-// RCS-ID:      $Id$
-// Licence:     wxWindows license
-/////////////////////////////////////////////////////////////////////////////
-
-/**
-Gets the name of a registered clipboard format, and puts it into the buffer @a
-formatName which is of maximum
-length @e maxCount. @a dataFormat must not specify a predefined clipboard
-format.
-*/
-bool wxGetClipboardFormatName(int dataFormat,
-                              const wxString& formatName,
-                              int maxCount);
-
-
-/**
-Gets data from the clipboard.
-@a dataFormat may be one of:
- wxCF_TEXT or wxCF_OEMTEXT: returns a pointer to new memory containing a
-null-terminated text string.
- wxCF_BITMAP: returns a new wxBitmap.
-The clipboard must have previously been opened for this call to succeed.
-*/
-wxObject* wxGetClipboardData(int dataFormat);
-
-/**
-    Returns @true if the given data format is available on the clipboard.
-*/
-bool wxIsClipboardFormatAvailable(int dataFormat);
-
-/**
-    Opens the clipboard for passing data to it or getting data from it.
-*/
-bool wxOpenClipboard();
-
-/**
-    Empties the clipboard.
-*/
-bool wxEmptyClipboard();
-
-/**
-    Returns @true if this application has already opened the clipboard.
-*/
-bool wxClipboardOpen();
-
-/**
-    Registers the clipboard data format name and returns an identifier.
-*/
-int wxRegisterClipboardFormat(const wxString& formatName);
-
-/**
-    Closes the clipboard to allow other applications to use it.
-*/
-bool wxCloseClipboard();
-
-/**
-    Enumerates the formats found in a list of available formats that belong
-    to the clipboard. Each call to this  function specifies a known
-    available format; the function returns the format that appears next in
-    the list.
-    @a dataFormat specifies a known format. If this parameter is zero,
-    the function returns the first format in the list.
-    The return value specifies the next known clipboard data format if the
-    function is successful. It is zero if the @a dataFormat parameter specifies
-    the last  format in the list of available formats, or if the clipboard
-    is not open.
-    Before it enumerates the formats function, an application must open the
-    clipboard by using the
-    wxOpenClipboard function.
-*/
-int wxEnumClipboardFormats(int dataFormat);
-

interface/docview.h

@@ -1448,10 +1448,28 @@ public:
 // Global functions/macros
 // ============================================================================
 
+/** @ingroup group_funcmacro_file */
+//@{
+
 /**
-    Copies the given file to @e stream. Useful when converting an old application to
+    Copies the given file to @a stream. Useful when converting an old
-    use streams (within the document/view framework, for example).
+    application to use streams (within the document/view framework, for
+    example).
+
+    @header{wx/docview.h}
 */
 bool wxTransferFileToStream(const wxString& filename,
                             ostream& stream);
 
+/**
+    Copies the given stream to the file @a filename. Useful when converting an
+    old application to use streams (within the document/view framework, for
+    example).
+
+    @header{wx/docview.h}
+*/
+bool wxTransferStreamToFile(istream& stream,
+                             const wxString& filename);
+
+//@}
+

interface/filefn.h

@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        filefn.h
-// Purpose:     interface of wxPathList
+// Purpose:     interface of wxPathList and file functions
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
@@ -11,12 +11,11 @@
     @wxheader{filefn.h}
 
     The path list is a convenient way of storing a number of directories, and
-    when presented with a filename without a directory, searching for an existing
+    when presented with a filename without a directory, searching for an
-    file
+    existing file in those directories.
-    in those directories.
 
-    Be sure to look also at wxStandardPaths if you only
+    Be sure to look also at wxStandardPaths if you only want to search files in
-    want to search files in some standard paths.
+    some standard paths.
 
     @library{wxbase}
     @category{file}
@@ -77,7 +76,7 @@ public:
     /**
         Searches the given file in all paths stored in this class.
         The first path which concatenated to the given string points to an existing
-        file (see @ref wxFile::exists wxFileExists) is returned.
+        file (see wxFileExists()) is returned.
         If the file wasn't found in any of the stored paths, an empty string is
         returned.
         The given string must be a file name, eventually with a path prefix (if the path
@@ -100,251 +99,360 @@ public:
 // Global functions/macros
 // ============================================================================
 
+/** @ingroup group_funcmacro_file */
+//@{
+
+/**
+    Under Unix this macro changes the current process umask to the given value,
+    unless it is equal to -1 in which case nothing is done, and restores it to
+    the original value on scope exit. It works by declaring a variable which
+    sets umask to @a mask in its constructor and restores it in its destructor.
+    Under other platforms this macro expands to nothing.
+
+    @header{wx/filefn.h}
+*/
+#define wxCHANGE_UMASK(int mask)
+
 /**
     This function returns the total number of bytes and number of free bytes on
-    the disk containing the directory @a path (it should exist). Both
+    the disk containing the directory @a path (it should exist). Both @a total
-    @a total and @a free parameters may be @NULL if the corresponding
+    and @a free parameters may be @NULL if the corresponding information is not
-    information is not needed.
+    needed.
+
+    @wxsince{2.3.2}
+
+    @note The generic Unix implementation depends on the system having the
+          @c statfs() or @c statvfs() function.
+
+    @returns @true on success, @false if an error occurred (for example, the
+             directory doesn’t exist).
+
+    @header{wx/filefn.h}
 */
 bool wxGetDiskSpace(const wxString& path,
                     wxLongLong total = NULL,
                     wxLongLong free = NULL);
 
 /**
-    Returns the Windows directory under Windows; on other platforms returns the
+    Returns the Windows directory under Windows; other platforms return an
     empty string.
+
+    @header{wx/filefn.h}
 */
 wxString wxGetOSDirectory();
 
 /**
-    Parses the @e wildCard, returning the number of filters.
+    Parses the @a wildCard, returning the number of filters. Returns 0 if none
-    Returns 0 if none or if there's a problem.
+    or if there's a problem.
-    The arrays will contain an equal number of items found before the error.
+
-    On platforms where native dialogs handle only one filter per entry,
+    The arrays will contain an equal number of items found before the error. On
-    entries in arrays are automatically adjusted.
+    platforms where native dialogs handle only one filter per entry, entries in
-    @a wildCard is in the form:
+    arrays are automatically adjusted. @a wildCard is in the form:
 
     @code
     "All files (*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png"
     @endcode
+
+    @header{wx/filefn.h}
 */
 int wxParseCommonDialogsFilter(const wxString& wildCard,
                                wxArrayString& descriptions,
                                wxArrayString& filters);
 
 /**
-    This function is deprecated, use wxFileName instead.
+    Converts a DOS to a Unix filename by replacing backslashes with forward
-    Converts a Unix to a DOS filename by replacing forward
+    slashes.
-    slashes with backslashes.
+
+    @header{wx/filefn.h}
+*/
+void wxDos2UnixFilename(wxChar* s);
+
+/**
+    @warning This function is deprecated, use wxFileName instead.
+
+    Converts a Unix to a DOS filename by replacing forward slashes with
+    backslashes.
+
+    @header{wx/filefn.h}
 */
 void wxUnix2DosFilename(wxChar* s);
 
 /**
     Returns @true if @a dirname exists and is a directory.
+
+    @header{wx/filefn.h}
 */
 bool wxDirExists(const wxString& dirname);
 
 /**
-    @b NB: This function is obsolete, please use
+    @warning This function is obsolete, please use wxFileName::SplitPath()
-    wxFileName::SplitPath instead.
+             instead.
+
     This function splits a full file name into components: the path (including
-    possible disk/drive
+    possible disk/drive specification under Windows), the base name, and the
-    specification under Windows), the base name and the extension. Any of the
+    extension. Any of the output parameters (@a path, @a name or @a ext) may be
-    output parameters
+    @NULL if you are not interested in the value of a particular component.
-    (@e path, @a name or @e ext) may be @NULL if you are not interested in the value
+
-    of
-    a particular component.
     wxSplitPath() will correctly handle filenames with both DOS and Unix path
-    separators under
+    separators under Windows, however it will not consider backslashes as path
-    Windows, however it will not consider backslashes as path separators under Unix
+    separators under Unix (where backslash is a valid character in a filename).
-    (where backslash
+
-    is a valid character in a filename).
     On entry, @a fullname should be non-@NULL (it may be empty though).
-    On return, @a path contains the file path (without the trailing separator), @e
+
-    name
+    On return, @a path contains the file path (without the trailing separator),
-    contains the file name and @a ext contains the file extension without leading
+    @a name contains the file name and @c ext contains the file extension
-    dot. All
+    without leading dot. All three of them may be empty if the corresponding
-    three of them may be empty if the corresponding component is. The old contents
+    component is. The old contents of the strings pointed to by these
-    of the
+    parameters will be overwritten in any case (if the pointers are not @NULL).
-    strings pointed to by these parameters will be overwritten in any case (if the
+
-    pointers
+    @header{wx/filefn.h}
-    are not @NULL).
 */
-void wxSplitPath(const wxString& fullname, wxString* path,
+void wxSplitPath(const wxString& fullname,
+                  wxString* path,
                   wxString* name,
                   wxString* ext);
 
-/**
-    Under Unix this macro changes the current process umask to the given value,
-    unless it is equal to -1 in which case nothing is done, and restores it to
-    the original value on scope exit. It works by declaring a variable which sets
-    umask to @a mask in its constructor and restores it in its destructor.
-    Under other platforms this macro expands to nothing.
-*/
-#define wxCHANGE_UMASK(int mask)     /* implementation is private */
-
 /**
     Returns time of last modification of given file.
-    The function returns @c (time_t)-1 if an error occurred (e.g. file not
+
-    found).
+    The function returns <tt>(time_t)-1</tt> if an error occurred (e.g. file
+    not found).
+
+    @header{wx/filefn.h}
 */
 time_t wxFileModificationTime(const wxString& filename);
 
-//@{
-/**
-    @b NB: This function is obsolete, please use
-    wxFileName::SplitPath instead.
-    Returns the filename for a full path. The second form returns a pointer to
-    temporary storage that should not be deallocated.
-*/
-wxString wxFileNameFromPath(const wxString& path);
-char* wxFileNameFromPath(char* path);
-//@}
-
 /**
     Renames @a file1 to @e file2, returning @true if successful.
+
     If @a overwrite parameter is @true (default), the destination file is
-    overwritten if it exists, but if @a overwrite is @false, the functions fails
+    overwritten if it exists, but if @a overwrite is @false, the functions
-    in this case.
+    fails in this case.
+
+    @header{wx/filefn.h}
 */
-bool wxRenameFile(const wxString& file1, const wxString& file2,
+bool wxRenameFile(const wxString& file1,
+                   const wxString& file2,
                    bool overwrite = true);
 
 /**
-    Copies @a file1 to @e file2, returning @true if successful. If
+    Copies @a file1 to @e file2, returning @true if successful. If @a overwrite
-    @a overwrite parameter is @true (default), the destination file is overwritten
+    parameter is @true (default), the destination file is overwritten if it
-    if it exists, but if @a overwrite is @false, the functions fails in this
+    exists, but if @a overwrite is @false, the functions fails in this case.
-    case.
+
     This function supports resources forks under Mac OS.
+
+    @header{wx/filefn.h}
 */
-bool wxCopyFile(const wxString& file1, const wxString& file2,
+bool wxCopyFile(const wxString& file1,
+                 const wxString& file2,
                  bool overwrite = true);
 
 /**
     Returns @true if the file exists and is a plain file.
+
+    @header{wx/filefn.h}
 */
 bool wxFileExists(const wxString& filename);
 
 /**
-    Returns @true if the @a pattern matches the @e text; if @a dot_special is @true,
+    Returns @true if the @a pattern matches the @e text; if @a dot_special is
-    filenames beginning with a dot are not matched
+    @true, filenames beginning with a dot are not matched with wildcard
-    with wildcard characters. See wxIsWild().
+    characters.
+
+    @see wxIsWild()
+
+    @header{wx/filefn.h}
 */
-bool wxMatchWild(const wxString& pattern, const wxString& text,
+bool wxMatchWild(const wxString& pattern,
+                  const wxString& text,
                   bool dot_special);
 
 /**
-    @b NB: This function is deprecated: use wxGetCwd() instead.
+    @warning This function is deprecated, use wxGetCwd() instead.
-    Copies the current working directory into the buffer if supplied, or
+
-    copies the working directory into new storage (which you must delete
+    Copies the current working directory into the buffer if supplied, or copies
-    yourself) if the buffer is @NULL.
+    the working directory into new storage (which you must delete yourself) if
+    the buffer is @NULL.
+
     @a sz is the size of the buffer if supplied.
+
+    @header{wx/filefn.h}
 */
 wxString wxGetWorkingDirectory(char* buf = NULL, int sz = 1000);
 
 /**
     Returns the directory part of the filename.
+
+    @header{wx/filefn.h}
 */
 wxString wxPathOnly(const wxString& path);
 
 /**
-    Returns @true if the pattern contains wildcards. See wxMatchWild().
+    Returns @true if the pattern contains wildcards.
+
+    @see wxMatchWild()
+
+    @header{wx/filefn.h}
 */
 bool wxIsWild(const wxString& pattern);
 
-/**
-    Returns a string containing the current (or working) directory.
-*/
-wxString wxGetCwd();
-
-/**
-    Converts a DOS to a Unix filename by replacing backslashes with forward
-    slashes.
-*/
-void wxDos2UnixFilename(wxChar* s);
-
-/**
-    Concatenates @a file1 and @a file2 to @e file3, returning
-    @true if successful.
-*/
-bool wxConcatFiles(const wxString& file1, const wxString& file2,
-                   const wxString& file3);
-
-/**
-    Removes @e file, returning @true if successful.
-*/
-bool wxRemoveFile(const wxString& file);
-
-/**
-    Sets the current working directory, returning @true if the operation succeeded.
-    Under MS Windows, the current drive is also changed if @a dir contains a drive
-    specification.
-*/
-bool wxSetWorkingDirectory(const wxString& dir);
-
-/**
-    Makes the directory @e dir, returning @true if successful.
-    @a perm is the access mask for the directory for the systems on which it is
-    supported (Unix) and doesn't have any effect on the other ones.
-*/
-bool wxMkdir(const wxString& dir, int perm = 0777);
-
 /**
     Returns @true if the argument is an absolute filename, i.e. with a slash
     or drive name at the beginning.
+
+    @header{wx/filefn.h}
 */
 bool wxIsAbsolutePath(const wxString& filename);
 
+/**
+    Returns a string containing the current (or working) directory.
+
+    @header{wx/filefn.h}
+*/
+wxString wxGetCwd();
+
+/**
+    Sets the current working directory, returning @true if the operation
+    succeeded. Under MS Windows, the current drive is also changed if @a dir
+    contains a drive specification.
+
+    @header{wx/filefn.h}
+*/
+bool wxSetWorkingDirectory(const wxString& dir);
+
+/**
+    Concatenates @a file1 and @a file2 to @e file3, returning @true if
+    successful.
+
+    @header{wx/filefn.h}
+*/
+bool wxConcatFiles(const wxString& file1,
+                    const wxString& file2,
+                    const wxString& file3);
+
+/**
+    Removes @e file, returning @true if successful.
+
+    @header{wx/filefn.h}
+*/
+bool wxRemoveFile(const wxString& file);
+
+/**
+    Makes the directory @a dir, returning @true if successful.
+
+    @a perm is the access mask for the directory for the systems on which it is
+    supported (Unix) and doesn't have any effect on the other ones.
+
+    @header{wx/filefn.h}
+*/
+bool wxMkdir(const wxString& dir, int perm = 0777);
+
+/**
+    Removes the directory @a dir, returning @true if successful. Does not work
+    under VMS.
+
+    The @a flags parameter is reserved for future use.
+
+    @note There is also a wxRmDir() function which simply wraps the standard
+          POSIX @c rmdir() function and so return an integer error code instead
+          of a boolean value (but otherwise is currently identical to
+          wxRmdir()), don't confuse these two functions.
+
+    @header{wx/filefn.h}
+*/
+bool wxRmdir(const wxString& dir, int flags = 0);
+
 /**
     Returns the next file that matches the path passed to wxFindFirstFile().
+
     See wxFindFirstFile() for an example.
+
+    @header{wx/filefn.h}
 */
 wxString wxFindNextFile();
 
 /**
-    This function does directory searching; returns the first file
+    This function does directory searching; returns the first file that matches
-    that matches the path @e spec, or the empty string. Use wxFindNextFile() to
+    the path @a spec, or the empty string. Use wxFindNextFile() to get the next
-    get the next matching file. Neither will report the current directory "." or the
+    matching file. Neither will report the current directory "." or the parent
-    parent directory "..".
+    directory "..".
+
+    @warning As of 2.5.2, these functions are not thread-safe! (they use static
+             variables). You probably want to use wxDir::GetFirst() or
+             wxDirTraverser instead.
+
+    @a spec may contain wildcards.
+
+    @a flags may be wxDIR for restricting the query to directories, wxFILE for
+    files or zero for either.
+
+    For example:
+
+    @code
+    wxString f = wxFindFirstFile("/home/project/*.*");
+    while ( !f.empty() )
+    {
+        ...
+        f = wxFindNextFile();
+    }
+    @endcode
+
+    @header{wx/filefn.h}
 */
 wxString wxFindFirstFile(const wxString& spec, int flags = 0);
 
+/**
+    File kind enumerations returned from wxGetFileKind().
+
+    @header{wx/filefn.h}
+*/
+enum wxFileKind
+{
+    wxFILE_KIND_UNKNOWN,  ///< Unknown file kind, or unable to determine
+    wxFILE_KIND_DISK,     ///< A file supporting seeking to arbitrary offsets
+    wxFILE_KIND_TERMINAL, ///< A tty
+    wxFILE_KIND_PIPE      ///< A pipe
+};
+
+//@}
+
+/** @ingroup group_funcmacro_file */
 //@{
 /**
-    Returns the type of an open file. Possible return values are:
+    Returns the type of an open file. Possible return values are enumerations
+    of ::wxFileKind.
 
-    @code
+    @header{wx/filefn.h}
-    enum wxFileKind
-    {
-      wxFILE_KIND_UNKNOWN,
-      wxFILE_KIND_DISK,     // a file supporting seeking to arbitrary offsets
-      wxFILE_KIND_TERMINAL, // a tty
-      wxFILE_KIND_PIPE      // a pipe
-    };
-    @endcode
 */
 wxFileKind wxGetFileKind(int fd);
 wxFileKind wxGetFileKind(FILE* fp);
 //@}
 
+/** @ingroup group_funcmacro_file */
 //@{
 /**
-    @b NB: These functions are obsolete, please use
+    @warning This function is obsolete, please use wxFileName::SplitPath()
-    wxFileName::CreateTempFileName
              instead.
+
+    Returns the filename for a full path. The second form returns a pointer to
+    temporary storage that should not be deallocated.
+
+    @header{wx/filefn.h}
+*/
+wxString wxFileNameFromPath(const wxString& path);
+char* wxFileNameFromPath(char* path);
+//@}
+
+/** @ingroup group_funcmacro_file */
+//@{
+/**
+    @warning This function is obsolete, please use
+             wxFileName::CreateTempFileName() instead.
+
+    @header{wx/filefn.h}
 */
 char* wxGetTempFileName(const wxString& prefix, char* buf = NULL);
 bool wxGetTempFileName(const wxString& prefix, wxString& buf);
 //@}
 
-/**
-    Removes the directory @e dir, returning @true if successful. Does not work under
-    VMS.
-    The @a flags parameter is reserved for future use.
-    Please notice that there is also a wxRmDir() function which simply wraps the
-    standard POSIX rmdir() function and so return an integer error code instead of
-    a boolean value (but otherwise is currently identical to wxRmdir), don't
-    confuse these two functions.
-*/
-bool wxRmdir(const wxString& dir, int flags = 0);
-

interface/utils.h

@@ -144,6 +144,57 @@ void wxInfoMessageBox(wxWindow parent = NULL);
 
 
 
+/** @ingroup group_funcmacro_env */
+//@{
+
+/**
+    This is a macro defined as @c getenv() or its wide char version in Unicode
+    mode.
+
+    Note that under Win32 it may not return correct value for the variables set
+    with wxSetEnv(), use wxGetEnv() function instead.
+
+    @header{wx/utils.h}
+*/
+wxChar* wxGetenv(const wxString& var);
+
+/**
+    Returns the current value of the environment variable @c var in @c value.
+    @c value may be @NULL if you just want to know if the variable exists and
+    are not interested in its value.
+
+    Returns @true if the variable exists, @false otherwise.
+
+    @header{wx/utils.h}
+*/
+bool wxGetEnv(const wxString& var, wxString* value);
+
+/**
+    Sets the value of the environment variable @c var (adding it if necessary)
+    to @c value.
+
+    Returns @true on success.
+
+    @see wxUnsetEnv()
+
+    @header{wx/utils.h}
+*/
+bool wxSetEnv(const wxString& var, const wxString& value);
+
+/**
+    Removes the variable @c var from the environment. wxGetEnv() will return
+    @NULL after the call to this function.
+
+    Returns @true on success.
+
+    @header{wx/utils.h}
+*/
+bool wxUnsetEnv(const wxString& var);
+
+//@}
+
+
+
 /**
     Returns the type of power source as one of @c wxPOWER_SOCKET,
     @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN.
@@ -455,17 +506,6 @@ wxString wxLoadUserResource(const wxString& resourceName,
 */
 wxMemorySize wxGetFreeMemory();
 
-/**
-    This is a macro defined as @c getenv() or its wide char version in Unicode
-    mode.
-    Note that under Win32 it may not return correct value for the variables set
-    with wxSetEnv(), use wxGetEnv() function
-    instead.
-
-    @header{wx/utils.h}
-*/
-wxChar* wxGetEnv(const wxString& var);
-
 //@{
 /**
     Copies the current host machine's name into the supplied buffer. Please note
@@ -486,16 +526,6 @@ wxString wxGetHostName();
 bool wxGetHostName(char* buf, int sz);
 //@}
 
-/**
-    Returns the current value of the environment variable @a var in @e value.
-    @a value may be @NULL if you just want to know if the variable exists
-    and are not interested in its value.
-    Returns @true if the variable exists, @false otherwise.
-
-    @header{wx/utils.h}
-*/
-bool wxGetEnv(const wxString& var, wxString* value);
-
 /**
     Under X only, returns the current display name. See also wxSetDisplayName().
 
@@ -723,17 +753,6 @@ bool wxGetEmailAddress(char* buf, int sz);
 */
 void wxSleep(int secs);
 
-/**
-    Sets the value of the environment variable @a var (adding it if necessary)
-    to @e value.
-    Returns @true on success.
-
-    @see wxUnsetEnv()
-
-    @header{wx/utils.h}
-*/
-bool wxSetEnv(const wxString& var, const wxString& value);
-
 /**
     Returns @true if the current platform is little endian (instead of big
     endian).