Add Doxygen support (#102)

CMakeLists.txt

@@ -3,6 +3,8 @@ project(zip)
 enable_language(C)
 set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
 
+set(ZIP_VERSION "0.1.15")
+
 if (MSVC)
   # Use secure functions by defaualt and suppress warnings about "deprecated" functions
   set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} /D _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES=1")
@@ -44,4 +46,13 @@ if(NOT TARGET uninstall)
 
     add_custom_target(uninstall
         COMMAND ${CMAKE_COMMAND} -P ${CMAKE_CURRENT_BINARY_DIR}/cmake/cmake_uninstall.cmake)
-endif()
+endif()
+
+find_package(Doxygen)
+if(DOXYGEN_FOUND)
+    configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
+    add_custom_target(doc
+        ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        COMMENT "Generating API documentation with Doxygen" VERBATIM)
+endif()

src/zip.h

@@ -25,9 +25,9 @@ extern "C" {
 // 64-bit Windows is the only mainstream platform
 // where sizeof(long) != sizeof(void*)
 #ifdef _WIN64
-typedef long long  ssize_t;  /* byte count or error */
+typedef long long ssize_t; /* byte count or error */
 #else
-typedef long  ssize_t;  /* byte count or error */
+typedef long ssize_t; /* byte count or error */
 #endif
 #endif
 
@@ -35,226 +35,216 @@ typedef long  ssize_t;  /* byte count or error */
 #define MAX_PATH 32767 /* # chars in a path name including NULL */
 #endif
 
+/**
+ * @mainpage
+ *
+ * Documenation for @ref zip.
+ */
+
+/**
+ * @addtogroup zip
+ * @{
+ */
+
+/**
+ * Default zip compression level.
+ */
+
 #define ZIP_DEFAULT_COMPRESSION_LEVEL 6
 
-/*
+/**
-  This data structure is used throughout the library to represent zip archive
+ * @struct zip_t
-  - forward declaration.
+ *
-*/
+ * This data structure is used throughout the library to represent zip archive -
+ * forward declaration.
+ */
 struct zip_t;
 
-/*
+/**
-  Opens zip archive with compression level using the given mode.
+ * Opens zip archive with compression level using the given mode.
-
+ *
-  Args:
+ * @param zipname zip archive file name.
-    zipname: zip archive file name.
+ * @param level compression level (0-9 are the standard zlib-style levels).
-    level: compression level (0-9 are the standard zlib-style levels).
+ * @param mode file access mode.
-    mode: file access mode.
+ *        - 'r': opens a file for reading/extracting (the file must exists).
-        'r': opens a file for reading/extracting (the file must exists).
+ *        - 'w': creates an empty file for writing.
-        'w': creates an empty file for writing.
+ *        - 'a': appends to an existing archive.
-        'a': appends to an existing archive.
+ *
-
+ * @return the zip archive handler or NULL on error
-  Returns:
+ */
-    The zip archive handler or NULL on error
-*/
 extern struct zip_t *zip_open(const char *zipname, int level, char mode);
 
-/*
+/**
-  Closes the zip archive, releases resources - always finalize.
+ * Closes the zip archive, releases resources - always finalize.
-
+ *
-  Args:
+ * @param zip zip archive handler.
-    zip: zip archive handler.
+ */
-*/
 extern void zip_close(struct zip_t *zip);
 
-/*
+/**
-  Opens an entry by name in the zip archive.
+ * Opens an entry by name in the zip archive.
-  For zip archive opened in 'w' or 'a' mode the function will append
+ *
-  a new entry. In readonly mode the function tries to locate the entry
+ * For zip archive opened in 'w' or 'a' mode the function will append
-  in global dictionary.
+ * a new entry. In readonly mode the function tries to locate the entry
-
+ * in global dictionary.
-  Args:
+ *
-    zip: zip archive handler.
+ * @param zip zip archive handler.
-    entryname: an entry name in local dictionary.
+ * @param entryname an entry name in local dictionary.
-
+ *
-  Returns:
+ * @return the return code - 0 on success, negative number (< 0) on error.
-    The return code - 0 on success, negative number (< 0) on error.
+ */
-*/
 extern int zip_entry_open(struct zip_t *zip, const char *entryname);
 
-/*
+/**
-  Opens a new entry by index in the zip archive.
+ * Opens a new entry by index in the zip archive.
-  This function is only valid if zip archive was opened in 'r' (readonly) mode.
+ *
-
+ * This function is only valid if zip archive was opened in 'r' (readonly) mode.
-  Args:
+ *
-    zip: zip archive handler.
+ * @param zip zip archive handler.
-    index: index in local dictionary.
+ * @param index index in local dictionary.
-
+ *
-  Returns:
+ * @return the return code - 0 on success, negative number (< 0) on error.
-    The return code - 0 on success, negative number (< 0) on error.
+ */
-*/
 extern int zip_entry_openbyindex(struct zip_t *zip, int index);
 
-/*
+/**
-  Closes a zip entry, flushes buffer and releases resources.
+ * Closes a zip entry, flushes buffer and releases resources.
-
+ *
-  Args:
+ * @param zip zip archive handler.
-    zip: zip archive handler.
+ *
-
+ * @return the return code - 0 on success, negative number (< 0) on error.
-  Returns:
+ */
-    The return code - 0 on success, negative number (< 0) on error.
-*/
 extern int zip_entry_close(struct zip_t *zip);
 
-/*
+/**
-  Returns a local name of the current zip entry.
+ * Returns a local name of the current zip entry.
-  The main difference between user's entry name and local entry name
+ *
-  is optional relative path.
+ * The main difference between user's entry name and local entry name
-  Following .ZIP File Format Specification - the path stored MUST not contain
+ * is optional relative path.
-  a drive or device letter, or a leading slash.
+ * Following .ZIP File Format Specification - the path stored MUST not contain
-  All slashes MUST be forward slashes '/' as opposed to backwards slashes '\'
+ * a drive or device letter, or a leading slash.
-  for compatibility with Amiga and UNIX file systems etc.
+ * All slashes MUST be forward slashes '/' as opposed to backwards slashes '\'
-
+ * for compatibility with Amiga and UNIX file systems etc.
-  Args:
+ *
-    zip: zip archive handler.
+ * @param zip: zip archive handler.
-
+ *
-  Returns:
+ * @return the pointer to the current zip entry name, or NULL on error.
-    The pointer to the current zip entry name, or NULL on error.
+ */
-*/
 extern const char *zip_entry_name(struct zip_t *zip);
 
-/*
+/**
-  Returns an index of the current zip entry.
+ * Returns an index of the current zip entry.
-
+ *
-  Args:
+ * @param zip zip archive handler.
-    zip: zip archive handler.
+ *
-
+ * @return the index on success, negative number (< 0) on error.
-  Returns:
+ */
-    The index on success, negative number (< 0) on error.
-*/
 extern int zip_entry_index(struct zip_t *zip);
 
-/*
+/**
-  Determines if the current zip entry is a directory entry.
+ * Determines if the current zip entry is a directory entry.
-
+ *
-  Args:
+ * @param zip zip archive handler.
-    zip: zip archive handler.
+ *
-
+ * @return the return code - 1 (true), 0 (false), negative number (< 0) on
-  Returns:
+ *         error.
-    The return code - 1 (true), 0 (false), negative number (< 0) on error.
+ */
-*/
 extern int zip_entry_isdir(struct zip_t *zip);
 
-/*
+/**
-  Returns an uncompressed size of the current zip entry.
+ * Returns an uncompressed size of the current zip entry.
-
+ *
-  Args:
+ * @param zip zip archive handler.
-    zip: zip archive handler.
+ *
-
+ * @return the uncompressed size in bytes.
-  Returns:
+ */
-    The uncompressed size in bytes.
-*/
 extern unsigned long long zip_entry_size(struct zip_t *zip);
 
-/*
+/**
-  Returns CRC-32 checksum of the current zip entry.
+ * Returns CRC-32 checksum of the current zip entry.
-
+ *
-  Args:
+ * @param zip zip archive handler.
-    zip: zip archive handler.
+ *
-
+ * @return the CRC-32 checksum.
-  Returns:
+ */
-    The CRC-32 checksum.
-*/
 extern unsigned int zip_entry_crc32(struct zip_t *zip);
 
-/*
+/**
-  Compresses an input buffer for the current zip entry.
+ * Compresses an input buffer for the current zip entry.
-
+ *
-  Args:
+ * @param zip zip archive handler.
-    zip: zip archive handler.
+ * @param buf input buffer.
-    buf: input buffer.
+ * @param bufsize input buffer size (in bytes).
-    bufsize: input buffer size (in bytes).
+ *
-
+ * @return the return code - 0 on success, negative number (< 0) on error.
-  Returns:
+ */
-    The return code - 0 on success, negative number (< 0) on error.
-*/
 extern int zip_entry_write(struct zip_t *zip, const void *buf, size_t bufsize);
 
-/*
+/**
-  Compresses a file for the current zip entry.
+ * Compresses a file for the current zip entry.
-
+ *
-  Args:
+ * @param zip zip archive handler.
-    zip: zip archive handler.
+ * @param filename input file.
-    filename: input file.
+ *
-
+ * @return the return code - 0 on success, negative number (< 0) on error.
-  Returns:
+ */
-    The return code - 0 on success, negative number (< 0) on error.
-*/
 extern int zip_entry_fwrite(struct zip_t *zip, const char *filename);
 
-/*
+/**
-  Extracts the current zip entry into output buffer.
+ * Extracts the current zip entry into output buffer.
-  The function allocates sufficient memory for a output buffer.
+ *
-
+ * The function allocates sufficient memory for a output buffer.
-  Args:
+ *
-    zip: zip archive handler.
+ * @param zip zip archive handler.
-    buf: output buffer.
+ * @param buf output buffer.
-    bufsize: output buffer size (in bytes).
+ * @param bufsize output buffer size (in bytes).
-
+ *
-  Note:
+ * @note remember to release memory allocated for a output buffer.
-    - remember to release memory allocated for a output buffer.
+ *       for large entries, please take a look at zip_entry_extract function.
-    - for large entries, please take a look at zip_entry_extract function.
+ *
-
+ * @return the return code - the number of bytes actually read on success.
-  Returns:
+ *         Otherwise a -1 on error.
-    The return code - the number of bytes actually read on success.
+ */
-    Otherwise a -1 on error.
-*/
 extern ssize_t zip_entry_read(struct zip_t *zip, void **buf, size_t *bufsize);
 
-/*
+/**
-  Extracts the current zip entry into a memory buffer using no memory
+ * Extracts the current zip entry into a memory buffer using no memory
-  allocation.
+ * allocation.
+ *
+ * @param zip zip archive handler.
+ * @param buf preallocated output buffer.
+ * @param bufsize output buffer size (in bytes).
+ *
+ * @note ensure supplied output buffer is large enough.
+ *       zip_entry_size function (returns uncompressed size for the current
+ *       entry) can be handy to estimate how big buffer is needed. for large
+ * entries, please take a look at zip_entry_extract function.
+ *
+ * @return the return code - the number of bytes actually read on success.
+ *         Otherwise a -1 on error (e.g. bufsize is not large enough).
+ */
+extern ssize_t zip_entry_noallocread(struct zip_t *zip, void *buf,
+                                     size_t bufsize);
 
-  Args:
+/**
-    zip: zip archive handler.
+ * Extracts the current zip entry into output file.
-    buf: preallocated output buffer.
+ *
-    bufsize: output buffer size (in bytes).
+ * @param zip zip archive handler.
-
+ * @param filename output file.
-  Note:
+ *
-    - ensure supplied output buffer is large enough.
+ * @return the return code - 0 on success, negative number (< 0) on error.
-    - zip_entry_size function (returns uncompressed size for the current entry)
+ */
-      can be handy to estimate how big buffer is needed.
-    - for large entries, please take a look at zip_entry_extract function.
-
-  Returns:
-    The return code - the number of bytes actually read on success.
-    Otherwise a -1 on error (e.g. bufsize is not large enough).
-*/
-extern ssize_t zip_entry_noallocread(struct zip_t *zip, void *buf, size_t bufsize);
-
-/*
-  Extracts the current zip entry into output file.
-
-  Args:
-    zip: zip archive handler.
-    filename: output file.
-
-  Returns:
-    The return code - 0 on success, negative number (< 0) on error.
-*/
 extern int zip_entry_fread(struct zip_t *zip, const char *filename);
 
-/*
+/**
-  Extracts the current zip entry using a callback function (on_extract).
+ * Extracts the current zip entry using a callback function (on_extract).
-
+ *
-  Args:
+ * @param zip zip archive handler.
-    zip: zip archive handler.
+ * @param on_extract callback function.
-    on_extract: callback function.
+ * @param arg opaque pointer (optional argument, which you can pass to the
-    arg: opaque pointer (optional argument,
+ *        on_extract callback)
-                         which you can pass to the on_extract callback)
+ *
-
+ * @return the return code - 0 on success, negative number (< 0) on error.
-   Returns:
-    The return code - 0 on success, negative number (< 0) on error.
  */
 extern int
 zip_entry_extract(struct zip_t *zip,
@@ -262,53 +252,49 @@ zip_entry_extract(struct zip_t *zip,
                                        const void *data, size_t size),
                   void *arg);
 
-/*
+/**
-  Returns the number of all entries (files and directories) in the zip archive.
+ * Returns the number of all entries (files and directories) in the zip archive.
-
+ *
-  Args:
+ * @param zip zip archive handler.
-    zip: zip archive handler.
+ *
-
+ * @return the return code - the number of entries on success, negative number
-  Returns:
+ *         (< 0) on error.
-    The return code - the number of entries on success,
+ */
-    negative number (< 0) on error.
-*/
 extern int zip_total_entries(struct zip_t *zip);
 
-/*
+/**
-  Creates a new archive and puts files into a single zip archive.
+ * Creates a new archive and puts files into a single zip archive.
-
+ *
-  Args:
+ * @param zipname zip archive file.
-    zipname: zip archive file.
+ * @param filenames input files.
-    filenames: input files.
+ * @param len: number of input files.
-    len: number of input files.
+ *
-
+ * @return the return code - 0 on success, negative number (< 0) on error.
-  Returns:
+ */
-    The return code - 0 on success, negative number (< 0) on error.
-*/
 extern int zip_create(const char *zipname, const char *filenames[], size_t len);
 
-/*
+/**
-  Extracts a zip archive file into directory.
+ * Extracts a zip archive file into directory.
-
+ *
-  If on_extract_entry is not NULL, the callback will be called after
+ * If on_extract_entry is not NULL, the callback will be called after
-  successfully extracted each zip entry.
+ * successfully extracted each zip entry.
-  Returning a negative value from the callback will cause abort and return an
+ * Returning a negative value from the callback will cause abort and return an
-  error. The last argument (void *arg) is optional, which you can use to pass
+ * error. The last argument (void *arg) is optional, which you can use to pass
-  data to the on_extract_entry callback.
+ * data to the on_extract_entry callback.
-
+ *
-  Args:
+ * @param zipname zip archive file.
-    zipname: zip archive file.
+ * @param dir output directory.
-    dir: output directory.
+ * @param on_extract_entry on extract callback.
-    on_extract_entry: on extract callback.
+ * @param arg opaque pointer.
-    arg: opaque pointer.
+ *
-
+ * @return the return code - 0 on success, negative number (< 0) on error.
-  Returns:
+ */
-    The return code - 0 on success, negative number (< 0) on error.
-*/
 extern int zip_extract(const char *zipname, const char *dir,
                        int (*on_extract_entry)(const char *filename, void *arg),
                        void *arg);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif