commit 5be5fea899302a04a0e892bcb37dbf264e2ad073
parent c70699d928757b842a9aba155cf34fe8f751dd6e
Author: Christian Grothoff <christian@grothoff.org>
Date: Thu, 22 Aug 2013 06:40:11 +0000
-doxygen fixes
Diffstat:
1 file changed, 31 insertions(+), 24 deletions(-)
diff --git a/src/include/extractor.h b/src/include/extractor.h
@@ -98,7 +98,7 @@ enum EXTRACTOR_MetaFormat
/**
* 0-terminated string. The specific encoding is unknown.
- * "data_len" is strlen(data)+1.
+ * "data_len" is strlen (data)+1.
*/
EXTRACTOR_METAFORMAT_C_STRING = 3
@@ -108,6 +108,9 @@ enum EXTRACTOR_MetaFormat
/**
* Enumeration defining various sources of keywords. See also
* http://dublincore.org/documents/1998/09/dces/
+ *
+ * @defgroup types meta data types
+ * @{
*/
enum EXTRACTOR_MetaType
{
@@ -383,6 +386,7 @@ enum EXTRACTOR_MetaType
EXTRACTOR_METATYPE_LAST = 228
};
+/** @} */ /* end of meta data types */
/**
* Get the textual name of the keyword.
@@ -390,7 +394,8 @@ enum EXTRACTOR_MetaType
* @param type meta type to get a UTF-8 string for
* @return NULL if the type is not known, otherwise
* an English (locale: C) string describing the type;
- * translate using 'dgettext ("libextractor", rval)'
+ * translate using `dgettext ("libextractor", rval)`
+ * @ingroup types
*/
const char *
EXTRACTOR_metatype_to_string (enum EXTRACTOR_MetaType type);
@@ -402,7 +407,8 @@ EXTRACTOR_metatype_to_string (enum EXTRACTOR_MetaType type);
* @param type meta type to get a UTF-8 description for
* @return NULL if the type is not known, otherwise
* an English (locale: C) string describing the type;
- * translate using 'dgettext ("libextractor", rval)'
+ * translate using `dgettext ("libextractor", rval)`
+ * @ingroup types
*/
const char *
EXTRACTOR_metatype_to_description (enum EXTRACTOR_MetaType type);
@@ -412,6 +418,7 @@ EXTRACTOR_metatype_to_description (enum EXTRACTOR_MetaType type);
* Return the highest type number, exclusive as in [0,max).
*
* @return highest legal metatype number for this version of libextractor
+ * @ingroup types
*/
enum EXTRACTOR_MetaType
EXTRACTOR_metatype_get_max (void);
@@ -427,11 +434,11 @@ EXTRACTOR_metatype_get_max (void);
* used in the main libextractor library and yielding
* meta data).
* @param type libextractor-type describing the meta data
- * @param format basic format information about data
- * @param data_mime_type mime-type of data (not of the original file);
+ * @param format basic format information about @a data
+ * @param data_mime_type mime-type of @a data (not of the original file);
* can be NULL (if mime-type is not known)
* @param data actual meta-data found
- * @param data_len number of bytes in data
+ * @param data_len number of bytes in @a data
* @return 0 to continue extracting, 1 to abort
*/
typedef int (*EXTRACTOR_MetaDataProcessor) (void *cls,
@@ -460,12 +467,12 @@ struct EXTRACTOR_ExtractContext
const char *config;
/**
- * Obtain a pointer to up to 'size' bytes of data from the file to process.
+ * Obtain a pointer to up to @a size bytes of data from the file to process.
*
- * @param cls the 'cls' member of this struct
+ * @param cls the @e cls member of this struct
* @param data pointer to set to the file data, set to NULL on error
* @param size maximum number of bytes requested
- * @return number of bytes now available in data (can be smaller than 'size'),
+ * @return number of bytes now available in @a data (can be smaller than @a size),
* -1 on error
*/
ssize_t (*read) (void *cls,
@@ -474,10 +481,10 @@ struct EXTRACTOR_ExtractContext
/**
- * Seek in the file. Use 'SEEK_CUR' for whence and 'pos' of 0 to
+ * Seek in the file. Use `SEEK_CUR` for @a whence and @a pos of 0 to
* obtain the current position in the file.
*
- * @param cls the 'cls' member of this struct
+ * @param cls the @e cls member of this struct
* @param pos position to seek (see 'man lseek')
* @param whence how to see (absolute to start, relative, absolute to end)
* @return new absolute position, -1 on error (i.e. desired position
@@ -491,8 +498,8 @@ struct EXTRACTOR_ExtractContext
/**
* Determine the overall size of the file.
*
- * @param cls the 'cls' member of this struct
- * @return overall file size, UINT64_MAX on error (i.e. IPC failure)
+ * @param cls the @a cls member of this struct
+ * @return overall file size, `UINT64_MAX` on error (i.e. IPC failure)
*/
uint64_t (*get_size) (void *cls);
@@ -517,7 +524,7 @@ typedef void (*EXTRACTOR_extract_method) (struct EXTRACTOR_ExtractContext *ec);
* Linked list of extractor plugins. An application builds this list
* by telling libextractor to load various keyword-extraction
* plugins. Libraries can also be unloaded (removed from this list,
- * see EXTRACTOR_plugin_remove).
+ * see #EXTRACTOR_plugin_remove).
*/
struct EXTRACTOR_PluginList;
@@ -526,7 +533,7 @@ struct EXTRACTOR_PluginList;
* Load the default set of plugins. The default can be changed
* by setting the LIBEXTRACTOR_LIBRARIES environment variable;
* If it is set to "env", then this function will return
- * EXTRACTOR_plugin_add_config (NULL, env, flags).
+ * #EXTRACTOR_plugin_add_config (NULL, env, flags).
*
* If LIBEXTRACTOR_LIBRARIES is not set, the function will attempt
* to locate the installed plugins and load all of them.
@@ -609,12 +616,12 @@ EXTRACTOR_plugin_remove_all (struct EXTRACTOR_PluginList *plugins);
* Extract keywords from a file using the given set of plugins.
*
* @param plugins the list of plugins to use
- * @param filename the name of the file, can be NULL if data is not NULL
+ * @param filename the name of the file, can be NULL if @a data is not NULL
* @param data data of the file in memory, can be NULL (in which
* case libextractor will open file) if filename is not NULL
- * @param size number of bytes in data, ignored if data is NULL
+ * @param size number of bytes in @a data, ignored if @a data is NULL
* @param proc function to call for each meta data item found
- * @param proc_cls cls argument to proc
+ * @param proc_cls cls argument to @a proc
*/
void
EXTRACTOR_extract (struct EXTRACTOR_PluginList *plugins,
@@ -626,23 +633,23 @@ EXTRACTOR_extract (struct EXTRACTOR_PluginList *plugins,
/**
- * Simple EXTRACTOR_MetaDataProcessor implementation that simply
+ * Simple #EXTRACTOR_MetaDataProcessor implementation that simply
* prints the extracted meta data to the given file. Only prints
* those keywords that are in UTF-8 format.
*
- * @param handle the file to write to (stdout, stderr), must NOT be NULL,
- * must be of type "FILE *".
+ * @param handle the file to write to (`stdout`, `stderr`), must NOT be NULL,
+ * must be of type `FILE *`.
* @param plugin_name name of the plugin that produced this value
* @param type libextractor-type describing the meta data
* @param format basic format information about data
- * @param data_mime_type mime-type of data (not of the original file);
+ * @param data_mime_type mime-type of @a data (not of the original file);
* can be NULL (if mime-type is not known)
* @param data actual meta-data found
- * @param data_len number of bytes in data
+ * @param data_len number of bytes in @a data
* @return non-zero if printing failed, otherwise 0.
*/
int
-EXTRACTOR_meta_data_print (void * handle,
+EXTRACTOR_meta_data_print (void *handle,
const char *plugin_name,
enum EXTRACTOR_MetaType type,
enum EXTRACTOR_MetaFormat format,
