revised archive header; changed overview_arc to overview_archive which reads better; modified the @category alias to point to the group pages and to spit out the @ingroup command

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

docs/doxygen/Doxyfile.inc

@@ -64,7 +64,8 @@ ALIASES += beginExtraStyleTable="<div><span class='styles'>Extra styles:</span>"
 ALIASES += endExtraStyleTable="</div>"
 
 # aliases for additional wx-specific infos
-ALIASES += category{1}="<div><span class='category'>Category:</span>&nbsp;&nbsp;<span class='category_text'>\ref page_class_cat_\1</span></div>"
+ALIASES += category{1}="\ingroup group_class_\1 \n<div><span class='category'>Category:</span>&nbsp;&nbsp;<span class='category_text'>\ref group_class_\1</span></div>"
+ALIASES += category{2}="\ingroup group_class_\1 group_class_\2 \n<div><span class='category'>Category:</span>&nbsp;&nbsp;<span class='category_text'>\ref group_class_\1, \ref group_class_\2</span></div>"
 ALIASES += library{1}="<div><span class='lib'>Library:</span>&nbsp;&nbsp;<span class='lib_text'>\ref page_libs_\1</span></div>"
 ALIASES += nolibrary="<div><span class='lib'>Library:</span>&nbsp;&nbsp;<span class='lib_text'>None; this class implementation is entirely header-based.</span></div>"
 ALIASES += stdobjects="<span class='stdobj'>Predefined objects:</span>"

docs/doxygen/groups/class_archive.h

@@ -0,0 +1,15 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        class_archive.h
+// Purpose:     wxArchive* classes group docs
+// Author:      wxWidgets team
+// RCS-ID:      $Id$
+// Licence:     wxWindows license
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+
+@defgroup group_class_archive Archive support
+@ingroup group_class
+
+*/
+

docs/doxygen/mainpages/cat_classes.h

@@ -50,6 +50,7 @@
 @li @ref page_class_cat_help
 @li @ref page_class_cat_media
 @li @ref page_class_cat_gl
+@li @ref page_class_cat_archive
 @li @ref page_class_cat_misc
 </td></tr>
 @endTable
@@ -785,6 +786,14 @@ Related Overviews: @ref overview_xrc
 
 
 
+@section page_class_cat_archive Archive
+
+@li wxArchiveInputStream
+@li wxArchiveOutputStream
+@li wxArchiveEntry
+
+
+
 @section page_class_cat_misc Miscellaneous
 
 @li wxCaret: A caret (cursor) object

docs/doxygen/mainpages/topics.h

@@ -62,7 +62,7 @@ The following is a basic categorization of them:
 @li @subpage overview_config
 @li @subpage overview_fs
 @li @subpage overview_resyntax
-@li @subpage overview_arc
+@li @subpage overview_archive
 @li @subpage overview_ipc
 
 @section page_topics_drawing Drawing Related Classes

docs/doxygen/overviews/archive.h

@@ -8,7 +8,7 @@
 
 /**
 
-@page overview_arc Archive Formats
+@page overview_archive Archive Formats
 
 The archive classes handle archive formats such as zip, tar, rar and cab.
 Currently wxZip and wxTar classes are included.
@@ -21,29 +21,29 @@ example):
 @li wxZipEntry: Holds meta-data for an entry (e.g. filename, timestamp, etc.)
 
 There are also abstract wxArchive classes that can be used to write code that
-can handle any of the archive types, see @ref overview_arc_generic.
+can handle any of the archive types, see @ref overview_archive_generic.
 
 Also see wxFileSystem for a higher level interface that can handle archive
 files in a generic way.
 
 The classes are designed to handle archives on both seekable streams such as
 disk files, or non-seekable streams such as pipes and sockets (see
-@ref overview_arc_noseek).
+@ref overview_archive_noseek).
 
 See also wxFileSystem.
 
-@li @ref overview_arc_create
+@li @ref overview_archive_create
-@li @ref overview_arc_extract
+@li @ref overview_archive_extract
-@li @ref overview_arc_modify
+@li @ref overview_archive_modify
-@li @ref overview_arc_byname
+@li @ref overview_archive_byname
-@li @ref overview_arc_generic
+@li @ref overview_archive_generic
-@li @ref overview_arc_noseek
+@li @ref overview_archive_noseek
 
 
 <hr>
 
 
-@section overview_arc_create Creating an Archive
+@section overview_archive_create Creating an Archive
 
 Call wxArchiveOutputStream::PutNextEntry() to create each new entry in the
 archive, then write the entry's data. Another call to PutNextEntry() closes the
@@ -66,7 +66,7 @@ The name of each entry can be a full path, which makes it possible to store
 entries in subdirectories.
 
 
-@section overview_arc_extract Extracting an Archive
+@section overview_archive_extract Extracting an Archive
 
 wxArchiveInputStream::GetNextEntry() returns a pointer to entry object
 containing the meta-data for the next entry in the archive (and gives away
@@ -93,7 +93,7 @@ while (entry.reset(zip.GetNextEntry()), entry.get() != NULL)
 
 
 
-@section overview_arc_modify Modifying an Archive
+@section overview_archive_modify Modifying an Archive
 
 To modify an existing archive, write a new copy of the archive to a new file,
 making any necessary changes along the way and transferring any unchanged
@@ -139,7 +139,7 @@ bool success = inzip.Eof() && outzip.Close() && out.Commit();
 
 
 
-@section overview_arc_byname Looking Up an Archive Entry by Name
+@section overview_archive_byname Looking Up an Archive Entry by Name
 
 Also see wxFileSystem for a higher level interface that is more convenient for
 accessing archive entries by name.
@@ -230,7 +230,7 @@ if ((it = cat.find(wxZipEntry::GetInternalName(local2))) != cat.end())
 
 
 
-@section overview_arc_generic Generic Archive Programming
+@section overview_archive_generic Generic Archive Programming
 
 Also see wxFileSystem for a higher level interface that can handle archive
 files in a generic way.
@@ -318,7 +318,7 @@ if (in->IsOk())
 
 
 
-@section overview_arc_noseek Archives on Non-Seekable Streams
+@section overview_archive_noseek Archives on Non-Seekable Streams
 
 In general, handling archives on non-seekable streams is done in the same way
 as for seekable streams, with a few caveats.
@@ -331,7 +331,7 @@ For each archive type, there will also be other limitations which will depend
 on the order the entries' meta-data is stored within the archive. These are not
 too difficult to deal with, and are outlined below.
 
-@subsection overview_arc_noseek_entrysize PutNextEntry and the Entry Size
+@subsection overview_archive_noseek_entrysize PutNextEntry and the Entry Size
 
 When writing archives, some archive formats store the entry size before the
 entry's data (tar has this limitation, zip doesn't). In this case the entry's
@@ -346,7 +346,7 @@ For generic programming, one way to handle this is to supply the size whenever
 it is known, and rely on the error message from the output stream when the
 operation is not supported.
 
-@subsection overview_arc_noseek_weak GetNextEntry and the Weak Reference Mechanism
+@subsection overview_archive_noseek_weak GetNextEntry and the Weak Reference Mechanism
 
 Some archive formats do not store all an entry's meta-data before the entry's
 data (zip is an example). In this case, when reading from a non-seekable
@@ -375,7 +375,7 @@ preserve entries' meta-data. No matter what order order the meta-data occurs
 within the archive, the input stream will always have read it before the output
 stream must write it.
 
-@subsection overview_arc_noseek_notifier wxArchiveNotifier
+@subsection overview_archive_noseek_notifier wxArchiveNotifier
 
 Notifier objects can be used to get a notification whenever an input stream
 updates a wxArchiveEntry object's data via the weak reference mechanism.

interface/archive.h

@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        archive.h
-// Purpose:     interface of wxArchiveInputStream
+// Purpose:     interface of wxArchive* classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
@@ -13,18 +13,19 @@
     An abstract base class which serves as a common interface to
     archive input streams such as wxZipInputStream.
 
-    wxArchiveInputStream::GetNextEntry returns an
+    wxArchiveInputStream::GetNextEntry returns an wxArchiveEntry object containing
-     wxArchiveEntry object containing the meta-data
+    the meta-data for the next entry in the archive (and gives away ownership).
-    for the next entry in the archive (and gives away ownership). Reading from
+
-    the wxArchiveInputStream then returns the entry's data. Eof() becomes @true
+    Reading from the wxArchiveInputStream then returns the entry's data. Eof()
-    after an attempt has been made to read past the end of the entry's data.
+    becomes @true after an attempt has been made to read past the end of the
+    entry's data.
+
     When there are no more entries, GetNextEntry() returns @NULL and sets Eof().
 
     @library{wxbase}
-    @category{FIXME}
+    @category{archive}
 
-    @see @ref overview_wxarc "Archive formats such as zip", wxArchiveEntry,
+    @see @ref overview_archive, wxArchiveEntry, wxArchiveOutputStream
-    wxArchiveOutputStream
 */
 class wxArchiveInputStream : public wxFilterInputStream
 {
@@ -37,18 +38,17 @@ public:
 
     /**
         Closes the current entry if one is open, then reads the meta-data for
-        the next entry and returns it in a wxArchiveEntry
+        the next entry and returns it in a wxArchiveEntry object, giving away
-        object, giving away ownership. Reading this wxArchiveInputStream then
+        ownership. Reading this wxArchiveInputStream then returns the entry's data.
-        returns the entry's data.
     */
     wxArchiveEntry* GetNextEntry();
 
     /**
         Closes the current entry if one is open, then opens the entry specified
         by the wxArchiveEntry object.
-        @a entry must be from the same archive file that this
+
-        wxArchiveInputStream is reading, and it must be reading it from a
+        @a entry must be from the same archive file that this wxArchiveInputStream
-        seekable stream.
+        is reading, and it must be reading it from a seekable stream.
     */
     bool OpenEntry(wxArchiveEntry& entry);
 };
@@ -62,23 +62,20 @@ public:
     An abstract base class which serves as a common interface to
     archive output streams such as wxZipOutputStream.
 
-    wxArchiveOutputStream::PutNextEntry is used
+    wxArchiveOutputStream::PutNextEntry is used to create a new entry in the
-    to create a new entry in the output archive, then the entry's data is
+    output archive, then the entry's data is written to the wxArchiveOutputStream.
-    written to the wxArchiveOutputStream.  Another call to PutNextEntry()
+    Another call to PutNextEntry() closes the current entry and begins the next.
-    closes the current entry and begins the next.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{archive}
 
-    @see @ref overview_wxarc "Archive formats such as zip", wxArchiveEntry,
+    @see @ref overview_archive, wxArchiveEntry, wxArchiveInputStream
-    wxArchiveInputStream
 */
 class wxArchiveOutputStream : public wxFilterOutputStream
 {
 public:
     /**
-        Calls Close() if it has not already
+        Calls Close() if it has not already been called.
-        been called.
     */
     ~wxArchiveOutputStream();
 
@@ -89,23 +86,24 @@ public:
     bool Close();
 
     /**
-        Close the current entry. It is called implicitly whenever another new
+        Close the current entry.
-        entry is created with CopyEntry()
+        It is called implicitly whenever another new entry is created with CopyEntry()
-        or PutNextEntry(), or
+        or PutNextEntry(), or when the archive is closed.
-        when the archive is closed.
     */
     bool CloseEntry();
 
     /**
         Some archive formats have additional meta-data that applies to the archive
-        as a whole.  For example in the case of zip there is a comment, which
+        as a whole.
-        is stored at the end of the zip file.  CopyArchiveMetaData() can be used
+        For example in the case of zip there is a comment, which is stored at the end
-        to transfer such information when writing a modified copy of an archive.
+        of the zip file.  CopyArchiveMetaData() can be used to transfer such information
+        when writing a modified copy of an archive.
+
         Since the position of the meta-data can vary between the various archive
         formats, it is best to call CopyArchiveMetaData() before transferring
-        the entries.  The wxArchiveOutputStream
+        the entries.  The wxArchiveOutputStream will then hold on to the meta-data
-        will then hold on to the meta-data and write it at the correct point in
+        and write it at the correct point in the output file.
-        the output file.
+
         When the input archive is being read from a non-seekable stream, the
         meta-data may not be available when CopyArchiveMetaData() is called,
         in which case the two streams set up a link and transfer the data
@@ -117,9 +115,11 @@ public:
         Takes ownership of @a entry and uses it to create a new entry in the
         archive. @a entry is then opened in the input stream @e stream
         and its contents copied to this stream.
+
         For archive types which compress entry data, CopyEntry() is likely to be
         much more efficient than transferring the data using Read() and Write()
         since it will copy them without decompressing and recompressing them.
+
         @a entry must be from the same archive file that @a stream is
         accessing. For non-seekable streams, @a entry must also be the last
         thing read from @e stream.
@@ -128,25 +128,26 @@ public:
                    wxArchiveInputStream& stream);
 
     /**
-        )
+        Create a new directory entry (see wxArchiveEntry::IsDir) with the given
-        Create a new directory entry
+        name and timestamp.
-        (see wxArchiveEntry::IsDir)
+
-        with the given name and timestamp.
+        PutNextEntry() can also be used to create directory entries, by supplying
-        PutNextEntry() can
+        a name with a trailing path separator.
-        also be used to create directory entries, by supplying a name with
-        a trailing path separator.
     */
     bool PutNextDirEntry(const wxString& name);
 
-    //@{
     /**
-        , @b off_t@e size = wxInvalidOffset)
+        Takes ownership of entry and uses it to create a new entry in the archive.
+        The entry's data can then be written by writing to this wxArchiveOutputStream.
+    */
+    bool PutNextEntry(wxArchiveEntry* entry);
+
+    /**
         Create a new entry with the given name, timestamp and size. The entry's
         data can then be written by writing to this wxArchiveOutputStream.
     */
-    bool PutNextEntry(wxArchiveEntry* entry);
+    bool PutNextEntry(const wxString& name, const wxDateTime& dt = wxDateTime::Now(),
-    bool PutNextEntry(const wxString& name);
+                      off_t size = wxInvalidOffset);
-    //@}
 };
 
 
@@ -160,11 +161,25 @@ public:
     These hold the meta-data (filename, timestamp, etc.), for entries
     in archive files such as zips and tars.
 
-    @library{wxbase}
+    <b>About non-seekable streams</b>: this information applies only when reading
-    @category{FIXME}
+    archives from non-seekable streams. When the stream is seekable GetNextEntry()
+    returns a fully populated wxArchiveEntry.
+    See @ref overview_archive_noseek for more information.
 
-    @see @ref overview_wxarc "Archive formats such as zip", @ref
+    For generic programming, when the worst case must be assumed, you can rely on
-    overview_wxarcgeneric "Generic archive programming", wxArchiveInputStream, wxArchiveOutputStream, wxArchiveNotifier
+    all the fields of wxArchiveEntry being fully populated when
+    wxArchiveInputStream::GetNextEntry() returns, with the the following exceptions:
+
+    @li GetSize(): guaranteed to be available after the entry has been read to Eof(),
+        or CloseEntry() has been called;
+    @li IsReadOnly(): guaranteed to be available after the end of the archive has
+        been reached, i.e. after GetNextEntry() returns NULL and Eof() is true.
+
+    @library{wxbase}
+    @category{archive}
+
+    @see @ref overview_archive, @ref overview_archive_generic,
+         wxArchiveInputStream, wxArchiveOutputStream, wxArchiveNotifier
 */
 class wxArchiveEntry : public wxObject
 {
@@ -174,34 +189,43 @@ public:
     */
     wxArchiveEntry* Clone() const;
 
-    //@{
     /**
-        The entry's timestamp.
+        Gets the entry's timestamp.
     */
     wxDateTime GetDateTime();
-    const void SetDateTime(const wxDateTime& dt);
-    //@}
 
-    //@{
     /**
-        The entry's name, by default in the native format. The name can include
+        Sets the entry's timestamp.
-        directory components, i.e. it can be a full path.
+    */
-        If this is a directory entry, (i.e. if IsDir()
+    const void SetDateTime(const wxDateTime& dt);
-        is @true) then GetName() returns the name with a trailing path separator.
+
-        Similarly, setting a name with a trailing path separator sets IsDir().
+    /**
+        Returns the entry's name, by default in the native format.
+        The name can include directory components, i.e. it can be a full path.
+
+        If this is a directory entry, (i.e. if IsDir() is @true) then the
+        returned string is the name with a trailing path separator.
     */
     wxString GetName(wxPathFormat format = wxPATH_NATIVE);
+
+    /**
+        Sets the entry's name.
+        Setting a name with a trailing path separator sets IsDir().
+
+        @see GetName()
+    */
     const void SetName(const wxString& name,
                        wxPathFormat format = wxPATH_NATIVE);
-    //@}
 
-    //@{
     /**
-        The size of the entry's data in bytes.
+        Returns the size of the entry's data in bytes.
     */
     off_t GetSize();
+
+    /**
+        Sets the size of the entry's data in bytes.
+    */
     const void SetSize(off_t size);
-    //@}
 
     /**
         Returns the path format used internally within the archive to store
@@ -213,10 +237,11 @@ public:
         Returns the entry's filename in the internal format used within the
         archive. The name can include directory components, i.e. it can be a
         full path.
+
         The names of directory entries are returned without any trailing path
         separator. This gives a canonical name that can be used in comparisons.
         
-        @see @ref overview_wxarcbyname "Looking up an archive entry by name"
+        @see @ref overview_archive_byname
     */
     wxString GetInternalName() const;
 
@@ -225,72 +250,91 @@ public:
     */
     off_t GetOffset() const;
 
-    //@{
     /**
-        True if this is a directory entry.
+        Returns @true if this is a directory entry.
+
         Directory entries are entries with no data, which are used to store
         the meta-data of directories. They also make it possible for completely
         empty directories to be stored.
+
+        @note
         The names of entries within an archive can be complete paths, and
         unarchivers typically create whatever directories are necessary as they
         restore files, even if the archive contains no explicit directory entries.
     */
     bool IsDir();
-    const void SetIsDir(bool isDir = true);
-    //@}
 
-    //@{
     /**
-        True if the entry is a read-only file.
+        Marks this entry as a directory if @a isDir is @true. See IsDir() for more info.
+    */
+    const void SetIsDir(bool isDir = true);
+
+    /**
+        Returns @true if the entry is a read-only file.
     */
     bool IsReadOnly();
-    const void SetIsReadOnly(bool isReadOnly = true);
-    //@}
 
-    //@{
     /**
-        Sets the notifier() for this entry.
+        Sets this entry as a read-only file.
-        Whenever the wxArchiveInputStream updates
+    */
-        this entry, it will then invoke the associated
+    const void SetIsReadOnly(bool isReadOnly = true);
-        notifier's wxArchiveNotifier::OnEntryUpdated
+
-        method.
+    /**
+        Sets the notifier (see wxArchiveNotifier) for this entry.
+
+        Whenever the wxArchiveInputStream updates this entry, it will then invoke
+        the associated notifier's wxArchiveNotifier::OnEntryUpdated method.
+
         Setting a notifier is not usually necessary. It is used to handle
         certain cases when modifying an archive in a pipeline (i.e. between
         non-seekable streams).
     */
     void SetNotifier(wxArchiveNotifier& notifier);
+
+    /**
+        Unsets the notifier eventually attached to this entry.
+    */
     void UnsetNotifier();
-    //@}
 };
 
 
+/**
+    Type of stream enumeration; used by wxArchiveClassFactory methods.
+*/
+enum wxStreamProtocolType
+{
+    wxSTREAM_PROTOCOL,  //!< wxFileSystem protocol (should be only one)
+    wxSTREAM_MIMETYPE,  //!< MIME types the stream handles
+    wxSTREAM_ENCODING,  //!< Not used for archives
+    wxSTREAM_FILEEXT    //!< File extensions the stream handles
+};
 
 /**
     @class wxArchiveClassFactory
     @wxheader{archive.h}
 
-    Allows the creation of streams to handle archive formats such
+    Allows the creation of streams to handle archive formats such as zip and tar.
-    as zip and tar.
 
     For example, given a filename you can search for a factory that will
     handle it and create a stream to read it:
 
     @code
-    factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);
+        factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);
         if (factory)
-            stream = factory-NewStream(new wxFFileInputStream(filename));
+            stream = factory->NewStream(new wxFFileInputStream(filename));
     @endcode
 
-    wxArchiveClassFactory::Find can also search
+    wxArchiveClassFactory::Find can also search for a factory by MIME type
-    for a factory by MIME type or wxFileSystem protocol.
+    or wxFileSystem protocol.
-    The available factories can be enumerated
+
-    using @ref wxArchiveClassFactory::getfirst "GetFirst() and GetNext".
+    The available factories can be enumerated using 
+    wxArchiveClassFactory::GetFirst() and wxArchiveClassFactory::GetNext().
 
     @library{wxbase}
-    @category{FIXME}
+    @category{archive}
 
-    @see @ref overview_wxarc "Archive formats such as zip", @ref
+    @see @ref overview_archive, @ref overview_archive_generic, wxArchiveEntry,
-    overview_wxarcgeneric "Generic archive programming", wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream, wxFilterClassFactory
+         wxArchiveInputStream, wxArchiveOutputStream, wxFilterClassFactory
 */
 class wxArchiveClassFactory : public wxObject
 {
@@ -298,6 +342,7 @@ public:
     /**
         Returns @true if this factory can handle the given protocol, MIME type
         or file extension.
+
         When using wxSTREAM_FILEEXT for the second parameter, the first parameter
         can be a complete filename rather than just an extension.
     */
@@ -308,28 +353,42 @@ public:
         A static member that finds a factory that can handle a given protocol, MIME
         type or file extension.  Returns a pointer to the class factory if found, or
         @NULL otherwise. It does not give away ownership of the factory.
+
         When using wxSTREAM_FILEEXT for the second parameter, the first parameter
         can be a complete filename rather than just an extension.
     */
     static const wxArchiveClassFactory* Find(const wxChar* protocol,
             wxStreamProtocolType type = wxSTREAM_PROTOCOL);
 
-    //@{
     /**
-        The wxMBConv object that the created streams
+        Returns the wxMBConv object that the created streams will use when
-        will use when translating meta-data. The initial default, set by the
+        translating meta-data. The initial default, set by the constructor,
-        constructor, is wxConvLocal.
+        is wxConvLocal.
     */
-    wxMBConv GetConv();
+    wxMBConv GetConv() const;
-    const void SetConv(wxMBConv& conv);
+
-    //@}
+    /**
+        Sets the wxMBConv object that the created streams will use when
+        translating meta-data.
+    */
+    void SetConv(wxMBConv& conv);
 
     //@{
     /**
         GetFirst and GetNext can be used to enumerate the available factories.
         For example, to list them:
 
-        GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
+        @code
+        wxString list;
+        const wxArchiveClassFactory *factory = wxArchiveClassFactory::GetFirst();
+    
+        while (factory) {
+            list << factory->GetProtocol() << _T("\n");
+            factory = factory->GetNext();
+        }
+        @endcode
+        
+        GetFirst() and GetNext() return a pointer to a factory or @NULL if no more
         are available. They do not give away ownership of the factory.
     */
     static const wxArchiveClassFactory* GetFirst() const;
@@ -338,50 +397,59 @@ public:
 
     /**
         Calls the static GetInternalName() function for the archive entry type,
-        for example
+        for example wxZipEntry::GetInternalName.
-         wxZipEntry::GetInternalName.
     */
     wxString GetInternalName(const wxString& name,
                              wxPathFormat format = wxPATH_NATIVE) const;
 
     /**
-        Returns the wxFileSystem protocol supported by this factory. Equivalent
+        Returns the wxFileSystem protocol supported by this factory.
-        to wxString(*GetProtcols()).
+        Equivalent to @code wxString(*GetProtocols()) @endcode.
     */
     wxString GetProtocol() const;
 
     /**
         Returns the protocols, MIME types or file extensions supported by this
-        factory, as an array of null terminated strings. It does not give away
+        factory, as an array of null terminated strings.
-        ownership of the array or strings.
+
+        It does not give away ownership of the array or strings.
         For example, to list the file extensions a factory supports:
+
+        @code
+        wxString list;
+        const wxChar *const *p;
+        
+        for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
+            list << *p << _T("\n");
+        @encode
     */
     const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
 
     /**
-        Create a new wxArchiveEntry object of the
+        Create a new wxArchiveEntry object of the appropriate type.
-        appropriate type.
     */
     wxArchiveEntry* NewEntry() const;
 
     //@{
     /**
         Create a new input or output stream to read or write an archive.
+
         If the parent stream is passed as a pointer then the new archive stream
         takes ownership of it. If it is passed by reference then it does not.
     */
     wxArchiveInputStream* NewStream(wxInputStream& stream) const;
-    const wxArchiveOutputStream*  NewStream(wxOutputStream& stream) const;
+    wxArchiveOutputStream* NewStream(wxOutputStream& stream) const;
-    const wxArchiveInputStream*  NewStream(wxInputStream* stream) const;
+    wxArchiveInputStream* NewStream(wxInputStream* stream) const;
-    const wxArchiveOutputStream*  NewStream(wxOutputStream* stream) const;
+    wxArchiveOutputStream* NewStream(wxOutputStream* stream) const;
     //@}
 
     /**
-        Adds this class factory to the list returned
+        Adds this class factory to the list returned by GetFirst() or GetNext().
-        by @ref getfirst() GetFirst()/GetNext.
+
         It is not necessary to do this to use the archive streams. It is usually
         used when implementing streams, typically the implementation will
         add a static instance of its factory class.
+
         It can also be used to change the order of a factory already in the list,
         bringing it to the front. This isn't a thread safe operation
         so can't be done when other threads are running that will be using the list.
@@ -390,10 +458,10 @@ public:
     void PushFront();
 
     /**
-        Removes this class factory from the list returned
+        Removes this class factory from the list returned by GetFirst() and GetNext().
-        by @ref getfirst() GetFirst()/GetNext.
+
-        Removing from the list isn't a thread safe operation
+        Removing from the list isn't a thread safe operation so can't be done when
-        so can't be done when other threads are running that will be using the list.
+        other threads are running that will be using the list.
         The list does not own the factories, so removing a factory does not delete it.
     */
     void Remove();
@@ -405,26 +473,25 @@ public:
     @class wxArchiveNotifier
     @wxheader{archive.h}
 
-    If you need to know when a
+    If you need to know when a wxArchiveInputStream updates a wxArchiveEntry
-     wxArchiveInputStream updates a
+    object, you can create a notifier by deriving from this abstract base class,
-     wxArchiveEntry object, you can create
+    overriding wxArchiveNotifier::OnEntryUpdated.
-    a notifier by deriving from this abstract base class, overriding
+
-     wxArchiveNotifier::OnEntryUpdated.  An instance
+    An instance of your notifier class can then be assigned to the wxArchiveEntry
-    of your notifier class can then be assigned to the wxArchiveEntry object
+    object using wxArchiveEntry::SetNotifier.
-    using wxArchiveEntry::SetNotifier.
     Your OnEntryUpdated() method will then be invoked whenever the input
     stream updates the entry.
 
     Setting a notifier is not usually necessary. It is used to handle
     certain cases when modifying an archive in a pipeline (i.e. between
     non-seekable streams).
-    See @ref overview_wxarcnoseek "Archives on non-seekable streams".
+    See @ref overview_archive_noseek.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{archive}
 
-    @see @ref overview_wxarcnoseek "Archives on non-seekable streams",
+    @see @ref overview_archive_noseek, wxArchiveEntry, wxArchiveInputStream,
-    wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream
+         wxArchiveOutputStream
 */
 class wxArchiveNotifier
 {
@@ -461,35 +528,34 @@ public:
     @endcode
 
     The first template parameter should be the type of archive input stream
-    (e.g. wxArchiveInputStream) and the
+    (e.g. wxArchiveInputStream) and the second can either be a pointer to an entry
-    second can either be a pointer to an entry
+    (e.g. wxArchiveEntry*), or a string/pointer pair (e.g. std::pairwxString, 
-    (e.g. wxArchiveEntry*), or a string/pointer pair
+    wxArchiveEntry*).
-    (e.g. std::pairwxString, wxArchiveEntry*).
 
     The @c wx/archive.h header defines the following typedefs:
 
     @code
-    typedef wxArchiveIteratorwxArchiveInputStream wxArchiveIter;
+    typedef wxArchiveIterator<wxArchiveInputStream> wxArchiveIter;
 
-        typedef wxArchiveIteratorwxArchiveInputStream,
+    typedef wxArchiveIterator<wxArchiveInputStream,
-                 std::pairwxString, wxArchiveEntry*  wxArchivePairIter;
+            std::pair<wxString, wxArchiveEntry*> > wxArchivePairIter;
     @endcode
 
     The header for any implementation of this interface should define similar
     typedefs for its types, for example in @c wx/zipstrm.h there is:
 
     @code
-    typedef wxArchiveIteratorwxZipInputStream wxZipIter;
+    typedef wxArchiveIterator<wxZipInputStream> wxZipIter;
 
-        typedef wxArchiveIteratorwxZipInputStream,
+    typedef wxArchiveIterator<wxZipInputStream,
-                 std::pairwxString, wxZipEntry*  wxZipPairIter;
+             std::pair<wxString, wxZipEntry*> > wxZipPairIter;
     @endcode
 
     Transferring the catalogue of an archive @e arc to a vector @e cat,
     can then be done something like this:
 
     @code
-    std::vectorwxArchiveEntry* cat((wxArchiveIter)arc, wxArchiveIter());
+        std::vector<wxArchiveEntry*> cat((wxArchiveIter)arc, wxArchiveIter());
     @endcode
 
     When the iterator is dereferenced, it gives away ownership of an entry
@@ -497,27 +563,26 @@ public:
     you must delete the pointers it contains.
 
     If you have smart pointers with normal copy semantics (i.e. not auto_ptr
-    or wxScopedPtr), then you can create an iterator
+    or wxScopedPtr), then you can create an iterator  which uses them instead.
-    which uses them instead.  For example, with a smart pointer class for
+
-    zip entries @e ZipEntryPtr:
+    For example, with a smart pointer class for zip entries @e ZipEntryPtr:
 
     @code
-    typedef std::vectorZipEntryPtr ZipCatalog;
+    typedef std::vector<ZipEntryPtr> ZipCatalog;
-        typedef wxArchiveIteratorwxZipInputStream, ZipEntryPtr ZipIter;
+    typedef wxArchiveIterator<wxZipInputStream, ZipEntryPtr> ZipIter;
-        ZipCatalog cat((ZipIter)zip, ZipIter());
+    ZipCatalog cat((ZipIter)zip, ZipIter());
     @endcode
 
-    Iterators that return std::pair objects can be used to
+    Iterators that return std::pair objects can be used to populate a std::multimap,
-    populate a std::multimap, to allow entries to be looked
+    to allow entries to be looked up by name.
-    up by name. The string is initialised using the wxArchiveEntry object's
+    The string is initialised using the wxArchiveEntry object's
-     wxArchiveEntry::GetInternalName function.
+    wxArchiveEntry::GetInternalName function.
 
     @code
-    typedef std::multimapwxString, wxZipEntry* ZipCatalog;
+    typedef std::multimap<wxString, wxZipEntry*> ZipCatalog;
-        ZipCatalog cat((wxZipPairIter)zip, wxZipPairIter());
+    ZipCatalog cat((wxZipPairIter)zip, wxZipPairIter());
     @endcode
 
-
     Note that this iterator also gives away ownership of an entry
     object each time it is dereferenced. So in the above example, when
     you have finished with @e cat you must delete the pointers it contains.
@@ -526,28 +591,30 @@ public:
     (again @e ZipEntryPtr), no worries about ownership:
 
     @code
-    typedef std::multimapwxString, ZipEntryPtr ZipCatalog;
+    typedef std::multimap<wxString, ZipEntryPtr> ZipCatalog;
-        typedef wxArchiveIteratorwxZipInputStream,
+    typedef wxArchiveIterator<wxZipInputStream,
-                    std::pairwxString, ZipEntryPtr  ZipPairIter;
+                std::pair<wxString, ZipEntryPtr> > ZipPairIter;
-        ZipCatalog cat((ZipPairIter)zip, ZipPairIter());
+    ZipCatalog cat((ZipPairIter)zip, ZipPairIter());
     @endcode
 
     @library{wxbase}
-    @category{FIXME}
+    @category{archive}
 
     @see wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream
 */
 class wxArchiveIterator
 {
 public:
-    //@{
     /**
-        Construct iterator that returns all the entries in the archive input
+        Default constructor.
-        stream @e arc.
     */
     wxArchiveIterator();
+
+    /**
+        Construct the iterator that returns all the entries in the archive input
+        stream @e arc.
+    */
     wxArchiveIterator(Arc& arc);
-    //@}
 
     /**
         Returns an entry object from the archive input stream, giving away
@@ -560,7 +627,7 @@ public:
         Position the input iterator at the next entry in the archive input stream.
     */
     wxArchiveIterator operator++();
-    wxArchiveIterator operator++(int );
+    wxArchiveIterator operator++(int);
     //@}
 };