add docu for ZIP classes

diff --git a/zip/qtzipbase.h b/zip/qtzipbase.h
index 441db75..2fc0168 100644 (file)
--- a/zip/qtzipbase.h
+++ b/zip/qtzipbase.h
@@ -35,14 +35,18 @@ THE SOFTWARE. */
 #endif
 
 namespace QtZipHelper {
-
+///Base class of Zip and Unzip, see those for details
 class ZIPHLP_EXPORT ZipHlpBase:public QObject
 {
         public:
+                ///create Zip object with parent
                 explicit ZipHlpBase(QObject* parent = 0);
+                ///delete the object
                 virtual ~ZipHlpBase();
                 
+                ///abstract base function: return true if the ZIP file is open
                 virtual bool isOpen()const =0;
+                ///abstract base function: close the ZIP file
                 virtual void close()=0;
         protected:
                 struct Private;

diff --git a/zip/qtzipbase_p.h b/zip/qtzipbase_p.h
index 2726c58..c16b3a1 100644 (file)
--- a/zip/qtzipbase_p.h
+++ b/zip/qtzipbase_p.h
@@ -30,6 +30,8 @@ THE SOFTWARE. */
 #include <QIODevice>
 
 class QIODevice;
+
+///\internal private data of ZipHlpBase
 struct QtZipHelper::ZipHlpBase::Private {
         QIODevice*device;
         zlib_filefunc_def ffunc;

diff --git a/zip/qtziphlp.h b/zip/qtziphlp.h
index f729a02..b953ced 100644 (file)
--- a/zip/qtziphlp.h
+++ b/zip/qtziphlp.h
@@ -34,26 +34,40 @@ namespace QtZipHelper {
 
 class Zip;
 class Unzip;
+
+///Helper class: reports information about a specific file entry in the ZIP archive.
 class ZIPHLP_EXPORT ZipFileInfo
 {
         public:
+                ///Empty/invalid info object.
                 ZipFileInfo();
+                ///Copy an info object.
                 ZipFileInfo(const ZipFileInfo&);
+                ///Copy an info object.
                 ZipFileInfo& operator=(const ZipFileInfo&);
                 
+                ///returns true if this is a valid info object
                 bool isValid()const{return !mName.isEmpty();}
                 
+                ///returns true if this is a valid info object, so the info object
+                ///can be used in if-statements directly
                 operator bool()const{return !mName.isEmpty();}
                 
+                ///returns the file name of the stored file
                 QString fileName()const{return mName;}
+                ///returns the creation time of the file stored in the ZIP
                 QDateTime createTime()const{return mTime;}
+                ///returns the code of the compression method used with this file
                 int rawCompressionMethod()const{return mMethod;}
+                ///returns the CRC32 stored for this file
                 ulong fileCRC()const{return mCRC;}
+                ///returns the uncompressed file size stored for this file
                 ulong uncompressedSize()const{return mUSize;}
                 
         private:
                 friend class Zip;
                 friend class Unzip;
+                ///\internal instantiates an info object with actual info
                 ZipFileInfo(const QString&,const QDateTime&,int,ulong,ulong);
                 
                 QDateTime mTime;
@@ -61,52 +75,98 @@ class ZIPHLP_EXPORT ZipFileInfo
                 int mMethod;
                 ulong mCRC,mUSize;
 };
-        
+
+///This class represents a ZIP file being assembled.
 class ZIPHLP_EXPORT Zip:public ZipHlpBase
 {
         Q_OBJECT
         friend class Unzip;
         public:
+                ///create a new ZIP object
                 explicit Zip(QObject* parent = 0);
+                ///delete the ZIP object and implicitly close it
                 virtual ~Zip();
+                
+                ///Defines how the ZIP file is opened.
                 enum OpenMode {
+                        ///Creates a fresh ZIP archive, even if the file exists.
                         OpenTruncate=0,
+                        ///If the file is new: create it, if it exists: append more files to the existing archive.
                         OpenAppend=1
                 };
+                ///returns true if the ZIP file is open for adding files
                 bool isOpen() const;
         public slots:
+                ///attached this ZIP object to the given device, does not take ownership of the device,
+                ///you are responsible for closing or reparenting it
                 virtual bool open(QIODevice *d, OpenMode mode=OpenTruncate);
+                ///closes the ZIP object (writing headers, trailers, etc.), but does not close the
+                ///actual QIODevice
                 virtual void close();
+                ///stores the content of the given QIODevice in the ZIP archive, compressing
+                ///it at the same time, the method assumes that the device is at the correct
+                ///position to start reading (i.e. if it is a file: you are responsible for
+                ///seeking to the start first)
                 virtual bool storeFile(const QString &name, QIODevice &file,
                         const QDateTime &time = QDateTime::currentDateTime());
+                ///stores the byte array as a file in the ZIP file, compressing it
                 virtual bool storeFile(const QString&name, QByteArray content,
                         const QDateTime &time = QDateTime::currentDateTime());
+                ///assumes the file is properly compressed and the info object contains the
+                ///correct information - use this for copying from an Unzip object
                 virtual bool storeRawFile(const ZipFileInfo&info, QIODevice &file);
+                ///assumes the file is properly compressed and the info object contains the
+                ///correct information - use this for copying from an Unzip object
                 virtual bool storeRawFile(const ZipFileInfo&info, QByteArray content);
 };
 
+///This class represents a ZIP file being read.
 class ZIPHLP_EXPORT Unzip:public ZipHlpBase
 {
         Q_OBJECT
         public:
+                ///create a new ZIP object
                 explicit Unzip(QObject*parent=0);
+                ///delete the ZIP object
                 virtual ~Unzip();
+                ///returns true if the ZIP file is currently open for reading
                 virtual bool isOpen() const;
         public slots:
+                ///attaches a QIODevice to the ZIP object, does not take ownership of the device,
+                ///you are responsible for closing or reparenting it
                 virtual bool open(QIODevice *d);
+                ///closes the ZIP object (abandoning internal state), but does not close the
+                ///actual QIODevice
                 virtual void close();
+                ///returns the amount of files stored in this ZIP file
                 virtual int fileCount()const;
+                ///jumps to the first file stored in the ZIP file, returning its information
                 virtual ZipFileInfo firstFile();
+                ///moves to the next file in the ZIP file, returning its information
                 virtual ZipFileInfo nextFile();
+                ///tries to find a file with the given name, returning its information
                 virtual ZipFileInfo locateFile(const QString &name, Qt::CaseSensitivity cs = Qt::CaseSensitive);
+                ///returns information about the file currently being unpacked
                 virtual ZipFileInfo currentFile()const;
+                ///returns information about the file currently being unpacked 
+                ///and stores its uncompressed content in the given QIODevice
                 virtual ZipFileInfo currentFile(QIODevice &d)const;
+                ///returns information about the file currently being unpacked 
+                ///and stores its uncompressed content in the given byte array
                 virtual ZipFileInfo currentFile(QByteArray&)const;
+                ///returns the uncompressed content of the current file
                 virtual QByteArray currentFileContent()const;
+                ///returns information about the file currently being unpacked 
+                ///and stores its still compressed content in the given QIODevice
                 virtual ZipFileInfo currentFileRaw(QIODevice &d)const;
+                ///returns information about the file currently being unpacked 
+                ///and stores its still compressed content in the given byte array
                 virtual ZipFileInfo currentFileRaw(QByteArray&)const;
+                ///returns the still compressed content of the current file
                 virtual QByteArray currentFileRawContent()const;
+                ///returns the name of the file currently being uncompressed
                 virtual QString currentFileName()const;
+                ///copies the current file to the given Zip object, returns true on success
                 virtual bool copyCurrentFile(Zip&)const;
 };