s/NB:/@note; revised wxFFile

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

interface/artprov.h

@@ -47,7 +47,7 @@
     wxArtProvider::GetIcon.
 
     @todo IS THIS NB TRUE?
-    (NB: this is not yet really possible as of wxWidgets 2.3.3, the set of wxArtProvider
+    (@note this is not yet really possible as of wxWidgets 2.3.3, the set of wxArtProvider
      bitmaps is too small).
 
     @section wxartprovider_identify Identifying art resources

interface/ffile.h

@@ -6,15 +6,43 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+
+
+/**
+    Values used for both wxFile and wxFFile.
+
+    @todo make the value names uppercase
+*/
+enum wxSeekMode
+{
+  wxFromStart,
+  wxFromCurrent,
+  wxFromEnd
+};
+
+/**
+    See wxFFile::GetKind().
+*/
+enum wxFileKind
+{
+  wxFILE_KIND_UNKNOWN,
+  wxFILE_KIND_DISK,     /**< A file supporting seeking to arbitrary offsets. */
+  wxFILE_KIND_TERMINAL, /**< A terminal. */
+  wxFILE_KIND_PIPE      /**< A pipe. */
+};
+
+
 /**
     @class wxFFile
     @wxheader{ffile.h}
 
-    wxFFile implements buffered file I/O. This is a very small class designed to
+    wxFFile implements buffered file I/O.
-    minimize the overhead of using it - in fact, there is hardly any overhead at
+
-    all, but using it brings you automatic error checking and hides differences
+    This is a very small class designed to minimize the overhead of using it - in fact,
-    between platforms and compilers. It wraps inside it a @c FILE * handle used
+    there is hardly any overhead at all, but using it brings you automatic error checking
-    by standard C IO library (also known as @c stdio).
+    and hides differences between platforms and compilers.
+
+    It wraps inside it a @c FILE * handle used by standard C IO library (also known as @c stdio).
 
     @library{wxbase}
     @category{file}
@@ -24,10 +52,22 @@
 class wxFFile
 {
 public:
-    //@{
+    wxFFile();
+
     /**
         Opens a file with the given file pointer, which has already been opened.
 
+        @param fp
+            An existing file descriptor, such as stderr.
+    */
+    wxFFile(FILE* fp);
+
+    /**
+        Opens a file with the given mode.
+        As there is no way to return whether the operation was successful or not from
+        the constructor you should test the return value of IsOpened() to check that it
+        didn't fail.
+
         @param filename
             The filename.
         @param mode
@@ -35,24 +75,21 @@ public:
             Note that you should use "b" flag if you use binary files under Windows
             or the results might be unexpected due to automatic newline conversion done
             for the text files.
-        @param fp
-            An existing file descriptor, such as stderr.
     */
-    wxFFile();
     wxFFile(const wxString& filename, const wxString& mode = "r");
-    wxFFile(FILE* fp);
+
-    //@}
 
     /**
         Destructor will close the file.
-        NB: it is not virtual so you should @e not derive from wxFFile!
+
+        @note it is not virtual so you should @e not derive from wxFFile!
     */
     ~wxFFile();
 
     /**
         Attaches an existing file pointer to the wxFFile object.
-        The descriptor should be already opened and it will be closed by wxFFile
+
-        object.
+        The descriptor should be already opened and it will be closed by wxFFile object.
     */
     void Attach(FILE* fp);
 
@@ -63,21 +100,24 @@ public:
 
     /**
         Get back a file pointer from wxFFile object -- the caller is responsible for
-        closing the file if this
+        closing the file if this descriptor is opened.
-        descriptor is opened. IsOpened() will return @false after call to Detach().
+
+        IsOpened() will return @false after call to Detach().
     */
     void Detach();
 
     /**
         Returns @true if the an attempt has been made to read @e past
         the end of the file.
-        Note that the behaviour of the file descriptor based class
+
-        wxFile is different as wxFile::Eof
+        Note that the behaviour of the file descriptor based class  wxFile is different as
-        will return @true here as soon as the last byte of the file has been
+        wxFile::Eof() will return @true here as soon as the last byte of the file has been read.
-        read.
+
         Also note that this method may only be called for opened files and may crash if
         the file is not opened.
 
+        @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD
+
         @see IsOpened()
     */
     bool Eof() const;
@@ -85,12 +125,15 @@ public:
     /**
         Returns @true if an error has occurred on this file, similar to the standard
         @c ferror() function.
+
         Please note that this method may only be called for opened files and may crash
         if the file is not opened.
 
+        @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD
+
         @see IsOpened()
     */
-
+    bool Error() const;
 
     /**
         Flushes the file and returns @true on success.
@@ -98,14 +141,16 @@ public:
     bool Flush();
 
     /**
-        Returns the type of the file. Possible return values are:
+        Returns the type of the file.
+
+        @see wxFileKind
     */
     wxFileKind GetKind() const;
 
     /**
-        Returns @true if the file is opened. Most of the methods of this class may
+        Returns @true if the file is opened.
-        only
+
-        be used for an opened file.
+        Most of the methods of this class may only be used for an opened file.
     */
     bool IsOpened() const;
 
@@ -125,8 +170,7 @@ public:
     bool Open(const wxString& filename, const wxString& mode = "r");
 
     /**
-        Reads the specified number of bytes into a buffer, returning the actual number
+        Reads the specified number of bytes into a buffer, returning the actual number read.
-        read.
 
         @param buffer
             A buffer to receive the data.
@@ -138,7 +182,6 @@ public:
     size_t Read(void* buffer, size_t count);
 
     /**
-        )
         Reads the entire contents of the file into a string.
 
         @param str
@@ -149,7 +192,7 @@ public:
 
         @returns @true if file was read successfully, @false otherwise.
     */
-    bool ReadAll(wxString* str);
+    bool ReadAll(wxString* str, const wxMBConv& conv = wxConvAuto());
 
     /**
         Seeks to the specified position and returns @true on success.
@@ -163,8 +206,7 @@ public:
 
     /**
         Moves the file pointer to the specified number of bytes before the end of the
-        file
+        file and returns @true on success.
-        and returns @true on success.
 
         @param ofs
             Number of bytes before the end of the file.
@@ -177,12 +219,24 @@ public:
     wxFileOffset Tell() const;
 
     /**
-        )
         Writes the contents of the string to the file, returns @true on success.
+
         The second argument is only meaningful in Unicode build of wxWidgets when
-        @e conv is used to convert @a s to multibyte representation.
+        @a conv is used to convert @a str to multibyte representation.
     */
-    bool Write(const wxString& s);
+    bool Write(const wxString& str, const wxMBConv& conv = wxConvAuto());
+
+    /**
+        Writes the specified number of bytes from a buffer.
+
+        @param buffer
+            A buffer containing the data.
+        @param count
+            The number of bytes to write.
+
+        @returns The number of bytes written.
+    */
+    size_t Write(const void* buffer, size_t count);
 
     /**
         Returns the file pointer associated with the file.

interface/grid.h

@@ -1960,7 +1960,7 @@ public:
     void InitColWidths();
 
     /**
-        NB: @e never access m_row/col arrays directly because they are created
+        @note @e never access m_row/col arrays directly because they are created
         on demand, @e always use accessor functions instead!
         Init the m_rowHeights/Bottoms arrays with default values.
     */

interface/mimetype.h

@@ -32,7 +32,7 @@
     If GNOME or KDE desktop environment is installed, then wxMimeTypesManager
     gathers MIME information from respective files (e.g. .kdelnk files under KDE).
 
-    NB: Currently, wxMimeTypesManager is limited to reading MIME type information
+    @note Currently, wxMimeTypesManager is limited to reading MIME type information
     but it will support modifying it as well in future versions.
 
     @library{wxbase}
@@ -63,7 +63,7 @@ public:
     void AddFallbacks(const wxFileTypeInfo* fallbacks);
 
     /**
-        NB: You won't normally need to use more than one wxMimeTypesManager object in a
+        @note You won't normally need to use more than one wxMimeTypesManager object in a
         program.
         @ref ctor() wxMimeTypesManager
 

interface/xml/xml.h

@@ -440,7 +440,7 @@ public:
     /**
         Returns encoding of in-memory representation of the document
         (same as passed to Load() or constructor, defaults to UTF-8).
-        NB: this is meaningless in Unicode build where data are stored as @c wchar_t*.
+        @note this is meaningless in Unicode build where data are stored as @c wchar_t*.
     */
     wxString GetEncoding() const;