[GNUnet-SVN] r28777 - Extractor/src/include

[gnunet]

Author: grothoff
Date: 2013-08-22 08:40:11 +0200 (Thu, 22 Aug 2013)
New Revision: 28777

Modified:
   Extractor/src/include/extractor.h
Log:
-doxygen fixes

Modified: Extractor/src/include/extractor.h
===================================================================
--- Extractor/src/include/extractor.h   2013-08-22 06:33:21 UTC (rev 28776)
+++ Extractor/src/include/extractor.h   2013-08-22 06:40:11 UTC (rev 28777)
@@ -98,7 +98,7 @@
 
     /**
      * 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 @@
 /**
  * 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 @@
     EXTRACTOR_METATYPE_LAST = 228
   };
 
+/** @} */ /* end of meta data types */
 
 /**
  * Get the textual name of the keyword.
@@ -390,7 +394,8 @@
  * @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 @@
  * @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 @@
  * 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 @@
  *        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 @@
   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 @@
 
   
   /**
-   * 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 @@
   /**
    * 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 @@
  * 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 @@
  * 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 @@
  * 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 @@
 
 
 /**
- * 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,