From ed41cad2bf505a24b88fefe423fee87bb4d1ceb5 Mon Sep 17 00:00:00 2001 From: Tomas Mlcoch Date: Tue, 2 Jul 2013 12:17:43 +0200 Subject: [PATCH] dic: Fix doxygen warnings. --- src/checksum.h | 2 ++ src/createrepo_c.h | 1 - src/repomd.h | 4 ++-- src/sqlite.h | 19 ++++++++++++------- src/threads.h | 14 +++++++------- src/xml_file.h | 31 ++++++++++++++++++++++++++----- src/xml_parser.h | 17 ++++++++++------- src/xml_parser_internal.h | 31 +++++++++++++++++++++---------- 8 files changed, 80 insertions(+), 39 deletions(-) diff --git a/src/checksum.h b/src/checksum.h index fc160ff..a7962f5 100644 --- a/src/checksum.h +++ b/src/checksum.h @@ -29,6 +29,8 @@ extern "C" { * @{ */ +/** Checksum context. + */ typedef struct _cr_ChecksumCtx cr_ChecksumCtx; /** diff --git a/src/createrepo_c.h b/src/createrepo_c.h index f501a29..5c40590 100644 --- a/src/createrepo_c.h +++ b/src/createrepo_c.h @@ -36,7 +36,6 @@ extern "C" { */ /** \defgroup main Complete API of createrepo_c library - * Usage: #include */ #include diff --git a/src/repomd.h b/src/repomd.h index 1acec82..6e1d9f9 100644 --- a/src/repomd.h +++ b/src/repomd.h @@ -90,8 +90,8 @@ typedef struct { /** Distro tag structure */ typedef struct { - gchar *cpeid; - gchar *val; + gchar *cpeid; /*!< cpeid value or NULL */ + gchar *val; /*!< Tag value */ } cr_DistroTag; /** Internal representation of cr_Repomd object diff --git a/src/sqlite.h b/src/sqlite.h index 6a68eeb..998556e 100644 --- a/src/sqlite.h +++ b/src/sqlite.h @@ -67,14 +67,19 @@ typedef enum { CR_DB_SENTINEL, /*!< sentinel of the list */ } cr_DatabaseType; -typedef struct _DbPrimaryStatements * cr_DbPrimaryStatements; -typedef struct _DbFilelistsStatements * cr_DbFilelistsStatements; -typedef struct _DbOtherStatements * cr_DbOtherStatements; - +typedef struct _DbPrimaryStatements * cr_DbPrimaryStatements; /*!< + Compiled primary database statements */ +typedef struct _DbFilelistsStatements * cr_DbFilelistsStatements; /*!< + Compiled filelists database statements */ +typedef struct _DbOtherStatements * cr_DbOtherStatements; /*!< + Compiled other database statements */ + +/** Union of precompiled database statements + */ typedef union { - cr_DbPrimaryStatements pri; - cr_DbFilelistsStatements fil; - cr_DbOtherStatements oth; + cr_DbPrimaryStatements pri; /*!< Primary statements */ + cr_DbFilelistsStatements fil; /*!< Filelists statements */ + cr_DbOtherStatements oth; /*!< Other statements */ } cr_Statements; /** cr_SqliteDb structure. diff --git a/src/threads.h b/src/threads.h index 8feff2e..2d554cd 100644 --- a/src/threads.h +++ b/src/threads.h @@ -64,8 +64,8 @@ extern "C" { * @{ */ -/** Compression */ - +/** Object representing a single compression task + */ typedef struct { char *src; /*!< Path to the original file. Must be specified by user. */ @@ -121,12 +121,12 @@ cr_compressiontask_free(cr_CompressionTask *task, GError **err); void cr_compressing_thread(gpointer data, gpointer user_data); -/** Repomd record fill */ - +/** Object representing a single repomd record fill task + */ typedef struct { - cr_RepomdRecord *record; - cr_ChecksumType checksum_type; - GError *err; + cr_RepomdRecord *record; /*!< Repomd record to be filled */ + cr_ChecksumType checksum_type; /*!< Type of checksum to be used */ + GError *err; /*!< GError ** */ } cr_RepomdRecordFillTask; /** Function to prepare a new cr_RepomdRecordFillTask. diff --git a/src/xml_file.h b/src/xml_file.h index d4ac0c3..6e5a6de 100644 --- a/src/xml_file.h +++ b/src/xml_file.h @@ -59,13 +59,20 @@ typedef struct { /** Open a new primary XML file. * @param FILENAME Filename. - * @param COMTYPE Type of used compression. + * @param COMTYPE Type of compression. * @param ERR GError ** * @return Opened cr_XmlFile or NULL on error */ #define cr_xmlfile_open_primary(FILENAME, COMTYPE, ERR) \ cr_xmlfile_open(FILENAME, CR_XMLFILE_PRIMARY, COMTYPE, ERR) +/** Open a new primary XML file. + * @param FILENAME Filename. + * @param COMTYPE Type of compression. + * @param STAT cr_ContentStat object or NULL. + * @param ERR GError ** + * @return Opened cr_XmlFile or NULL on error + */ #define cr_xmlfile_sopen_primary(FILENAME, COMTYPE, STAT, ERR) \ cr_xmlfile_sopen(FILENAME, CR_XMLFILE_PRIMARY, COMTYPE, STAT, ERR) @@ -78,6 +85,13 @@ typedef struct { #define cr_xmlfile_open_filelists(FILENAME, COMTYPE, ERR) \ cr_xmlfile_open(FILENAME, CR_XMLFILE_FILELISTS, COMTYPE, ERR) +/** Open a new filelists XML file. + * @param FILENAME Filename. + * @param COMTYPE Type of compression. + * @param STAT cr_ContentStat object or NULL. + * @param ERR GError ** + * @return Opened cr_XmlFile or NULL on error + */ #define cr_xmlfile_sopen_filelists(FILENAME, COMTYPE, STAT, ERR) \ cr_xmlfile_sopen(FILENAME, CR_XMLFILE_FILELISTS, COMTYPE, STAT, ERR) @@ -90,16 +104,23 @@ typedef struct { #define cr_xmlfile_open_other(FILENAME, COMTYPE, ERR) \ cr_xmlfile_open(FILENAME, CR_XMLFILE_OTHER, COMTYPE, ERR) +/** Open a new other XML file. + * @param FILENAME Filename. + * @param COMTYPE Type of compression. + * @param STAT cr_ContentStat object or NULL. + * @param ERR GError ** + * @return Opened cr_XmlFile or NULL on error + */ #define cr_xmlfile_sopen_other(FILENAME, COMTYPE, STAT, ERR) \ cr_xmlfile_sopen(FILENAME, CR_XMLFILE_OTHER, COMTYPE, STAT, ERR) /** Open a new XML file with stats. * Note: Opened file must not exists! This function cannot * open existing file!. - * @param filename Filename. - * @param type Type of XML file. - * @param comtype Type of used compression. - * @param err **GError + * @param FILENAME Filename. + * @param TYPE Type of XML file. + * @param COMTYPE Type of used compression. + * @param ERR **GError * @return Opened cr_XmlFile or NULL on error */ #define cr_xmlfile_open(FILENAME, TYPE, COMTYPE, ERR) \ diff --git a/src/xml_parser.h b/src/xml_parser.h index 0679023..55098c1 100644 --- a/src/xml_parser.h +++ b/src/xml_parser.h @@ -32,9 +32,11 @@ extern "C" { * @{ */ -#define CR_CB_RET_OK 0 -#define CR_CB_RET_ERR 1 +#define CR_CB_RET_OK 0 /*!< Return value for callbacks signalizing success */ +#define CR_CB_RET_ERR 1 /*!< Return value for callbacks signalizing error */ +/** Type of warnings reported by parsers by the warning callback. + */ typedef enum { CR_XML_WARNING_UNKNOWNTAG, /*!< Unknown tag */ CR_XML_WARNING_MISSINGATTR, /*!< Missing attribute */ @@ -70,7 +72,7 @@ typedef int (*cr_XmlParserNewPkgCb)(cr_Package **pkg, /** Callback for XML parser wich is called when a package element is parsed. * @param pkg Currently parsed package. * @param cbdata User data. - * @err GError ** + * @param err GError ** * @return CR_CB_RET_OK (0) or CR_CB_RET_ERR (1) - stops the parsing */ typedef int (*cr_XmlParserPkgCb)(cr_Package *pkg, @@ -93,7 +95,7 @@ typedef int (*cr_XmlParserWarningCb)(cr_XmlParserWarningType type, GError **err); /** Parse primary.xml. File could be compressed. - * @param path Path to filelists.xml (plain or compressed) + * @param path Path to filelists.xml * @param newpkgcb Callback for new package (Called when new package * xml chunk is found and package object to store * the data is needed). If NULL cr_newpkgcb is used. @@ -119,7 +121,7 @@ int cr_xml_parse_primary(const char *path, GError **err); /** Parse filelists.xml. File could be compressed. - * @param path Path to filelists.xml (plain or compressed) + * @param path Path to filelists.xml * @param newpkgcb Callback for new package (Called when new package * xml chunk is found and package object to store * the data is needed). If NULL cr_newpkgcb is used. @@ -143,7 +145,7 @@ int cr_xml_parse_filelists(const char *path, GError **err); /** Parse other.xml. File could be compressed. - * @param path Path to other.xml (plain or compressed) + * @param path Path to other.xml * @param newpkgcb Callback for new package (Called when new package * xml chunk is found and package object to store * the data is needed). If NULL cr_newpkgcb is used. @@ -167,7 +169,8 @@ int cr_xml_parse_other(const char *path, GError **err); /** Parse repomd.xml. File could be compressed. - * @param repom cr_Repomd object. + * @param path Path to repomd.xml + * @param repomd cr_Repomd object. * @param warningcb Callback for warning messages. * @param warningcb_data User data for the warningcb. * @param err GError ** diff --git a/src/xml_parser_internal.h b/src/xml_parser_internal.h index 6e58ef0..a98a470 100644 --- a/src/xml_parser_internal.h +++ b/src/xml_parser_internal.h @@ -43,7 +43,8 @@ extern "C" { * of the callback has to set the GError by himself. */ -/* File types in filelists.xml */ +/** File types in filelists.xml + */ typedef enum { FILE_FILE, FILE_DIR, @@ -51,6 +52,8 @@ typedef enum { FILE_SENTINEL, } cr_FileType; +/** Structure used for elements in the state switches in XML parsers + */ typedef struct { unsigned int from; /*!< State (current tag) */ char *ename; /*!< String name of sub-tag */ @@ -58,9 +61,11 @@ typedef struct { int docontent; /*!< Read text content of element? */ } cr_StatesSwitch; +/** Parser data + */ typedef struct _cr_ParserData { - int depth; - int statedepth; + int depth; /*!< Current depth in a XML tree */ + int statedepth; /*!< Depth of the last known state (element) */ unsigned int state; /*!< current state */ GError *err; /*!< Error message */ @@ -78,7 +83,7 @@ typedef struct _cr_ParserData { /* Package stuff */ - void *newpkgcb_data; /*!< + void *newpkgcb_data; /*!< User data for the newpkgcb. */ cr_XmlParserNewPkgCb newpkgcb; /*!< Callback called to get (create new or use existing from a previous @@ -90,7 +95,8 @@ typedef struct _cr_ParserData { Callback called when a signel pkg data are completly parsed. */ void *warningcb_data; /*!< User data fot he warningcb. */ - cr_XmlParserWarningCb warningcb; + cr_XmlParserWarningCb warningcb; /*!< + Warning callback */ cr_Package *pkg; /*!< The package which is currently loaded. */ @@ -107,17 +113,22 @@ typedef struct _cr_ParserData { /* Filelists + Primary related stuff */ - cr_FileType last_file_type; + cr_FileType last_file_type; /*!< + Type of file in a currently parsed element */ /* Other related stuff */ - cr_ChangelogEntry *changelog; + cr_ChangelogEntry *changelog; /*!< + Changelog entry object for currently parsed element (entry) */ /* Repomd related stuff */ - cr_Repomd *repomd; - cr_RepomdRecord *repomdrecord; - char *cpeid; + cr_Repomd *repomd; /*!< + Repomd object */ + cr_RepomdRecord *repomdrecord; /*!< + Repomd record object for a currently parsed element */ + char *cpeid; /*!< + cpeid value for the currently parsed distro tag */ } cr_ParserData; -- 2.7.4