more doxygen markup + fixes

git-svn-id: https://svn.code.sf.net/p/gphoto/code/trunk/libgphoto2@10309 67ed7778-7388-44ab-90cf-0a291f65f57c

4 files changed, 197 insertions, 87 deletions

diff --git a/libgphoto2_port/libgphoto2_port/gphoto2-port-info-list.c b/libgphoto2_port/libgphoto2_port/gphoto2-port-info-list.c
index 6fd9c7cd7..c0055b807 100644
--- a/libgphoto2_port/libgphoto2_port/gphoto2-port-info-list.c
+++ b/libgphoto2_port/libgphoto2_port/gphoto2-port-info-list.c
@@ -1,17 +1,20 @@
 /** \file
  *
- * Copyright © 2001 Lutz Müller <lutz@users.sf.net>
+ * \author Copyright 2001 Lutz Müller <lutz@users.sf.net>
  *
+ * \par License
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
  * License as published by the Free Software Foundation; either
  * version 2 of the License, or (at your option) any later version.
  *
+ * \par
  * This library is distributed in the hope that it will be useful, 
  * but WITHOUT ANY WARRANTY; without even the implied warranty of 
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Lesser General Public License for more details. 
  *
+ * \par
  * You should have received a copy of the GNU Lesser General Public
  * License along with this library; if not, write to the
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
@@ -78,19 +81,32 @@ struct _GPPortInfoList {
  **/
 #define IOLIBDIR_ENV "IOLIBS"
 
+/**
+ * \brief Specify codeset for translations
+ *
+ * This function specifies the codeset that are used for the translated
+ * strings that are passed back by the libgphoto2_port functions.
+ *
+ * This function is called by the gp_message_codeset() function, there is
+ * no need to call it yourself.
+ * 
+ * \param codeset new codeset to use
+ * \return the previous codeset
+ */
 const char*
 gp_port_message_codeset (const char *codeset) {
 	return bind_textdomain_codeset (GETTEXT_PACKAGE, codeset);
 }
 
 /**
- * gp_port_info_list_new:
- * @list:
+ * \brief Create a new GPPortInfoList
+ *
+ * \param list pointer to a GPPortInfoList* which is allocated
  *
  * Creates a new list which can later be filled with port infos (#GPPortInfo)
  * using #gp_port_info_list_load.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_port_info_list_new (GPPortInfoList **list)
@@ -112,12 +128,12 @@ gp_port_info_list_new (GPPortInfoList **list)
 }
 
 /**
- * gp_port_info_list_free:
- * @list: a #GPPortInfoList
+ * \brief Free a GPPortInfo list
+ * \param list a #GPPortInfoList
  *
- * Frees a @list.
+ * Frees a GPPortInfoList structure and its internal data structures.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_port_info_list_free (GPPortInfoList *list)
@@ -136,19 +152,20 @@ gp_port_info_list_free (GPPortInfoList *list)
 }
 
 /**
- * gp_port_info_list_append:
- * @list: a #GPPortInfoList
- * @info: the info to append
+ * \brief Append a portinfo to the port information list
  *
- * Appends an entry to the @list. This function is typically called by
+ * \param list a #GPPortInfoList
+ * \param info the info to append
+ *
+ * Appends an entry to the list. This function is typically called by
  * an io-driver during #gp_port_library_list. If you leave info.name blank,
  * #gp_port_info_list_lookup_path will try to match non-existent paths
  * against info.path and - if successfull - will append this entry to the 
  * list.
  *
- * NOTE: This returns index - number of generic entries, not the correct index.
+ * \note This returns index - number of generic entries, not the correct index.
  *
- * Return value: A non-negative number or a gphoto2 error code
+ * \return A non-negative number or a gphoto2 error code
  **/
 int
 gp_port_info_list_append (GPPortInfoList *list, GPPortInfo info)
@@ -243,14 +260,16 @@ foreach_func (const char *filename, lt_ptr data)
 
 
 /**
- * gp_port_info_list_load:
- * @list: a #GPPortInfoList
+ * \brief Load system ports
+ * 
+ * \param list a #GPPortInfoList
  *
  * Searches the system for io-drivers and appends them to the list. You would
  * normally call this function once after #gp_port_info_list_new and then
- * use this list in order to supply #gp_port_set_info with parameters.
+ * use this list in order to supply #gp_port_set_info with parameters or to do
+ * autodetection.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_port_info_list_load (GPPortInfoList *list)
@@ -274,12 +293,12 @@ gp_port_info_list_load (GPPortInfoList *list)
 }
 
 /**
- * gp_port_info_list_count:
- * @list: a #GPPortInfoList
+ * \brief Number of ports in the list
+ * \param list a #GPPortInfoList
  *
- * Returns the number of entries in the @list.
+ * Returns the number of entries in the passed list.
  *
- * Return value: The number of entries or a gphoto2 error code
+ * \return The number of entries or a gphoto2 error code
  **/
 int
 gp_port_info_list_count (GPPortInfoList *list)
@@ -303,15 +322,16 @@ gp_port_info_list_count (GPPortInfoList *list)
 }
 
 /**
- * gp_port_info_list_lookup_path:
- * @list: a #GPPortInfoList
- * @path: a path
+ * \brief Lookup a specific path in the list
+ *
+ * \param list a #GPPortInfoList
+ * \param path a path
  *
- * Looks for an entry in the list with the supplied @path. If no exact match
+ * Looks for an entry in the list with the supplied path. If no exact match
  * can be found, a regex search will be performed in the hope some driver
  * claimed ports like "serial:*".
  *
- * Return value: The index of the entry or a gphoto2 error code
+ * \return The index of the entry or a gphoto2 error code
  **/
 int
 gp_port_info_list_lookup_path (GPPortInfoList *list, const char *path)
@@ -401,13 +421,13 @@ gp_port_info_list_lookup_path (GPPortInfoList *list, const char *path)
 }
 
 /**
- * gp_port_info_list_lookup_name:
- * @list: a #GPPortInfoList
- * @name: a name
+ * \brief Look up a name in the list
+ * \param list a #GPPortInfoList
+ * \param name a name
  *
- * Looks for an entry in the @list with the given @name.
+ * Looks for an entry in the list with the exact given name.
  *
- * Return value: The index of the entry or a gphoto2 error code
+ * \return The index of the entry or a gphoto2 error code
  **/
 int
 gp_port_info_list_lookup_name (GPPortInfoList *list, const char *name)
@@ -430,14 +450,14 @@ gp_port_info_list_lookup_name (GPPortInfoList *list, const char *name)
 }
 
 /**
- * gp_port_info_list_get_info:
- * @list: a #GPPortInfoList
- * @n: the index of the entry
- * @info:
+ * \brief Get port information of specific entry
+ * \param list a #GPPortInfoList
+ * \param n the index of the entry
+ * \param info the returned information
  *
- * Retreives an entry from the @list.
+ * Retreives an entry from the list and stores it into info.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_port_info_list_get_info (GPPortInfoList *list, int n, GPPortInfo *info)
@@ -467,6 +487,12 @@ gp_port_info_list_get_info (GPPortInfoList *list, int n, GPPortInfo *info)
 
 
 #ifdef _GPHOTO2_INTERNAL_CODE
+/**
+ * \brief Internal map between GP_PORT and name
+ * 
+ * Internal map between the GP_PORT_xxx enumeration and
+ * string names (usb,serial,disk,ptpip,...).
+ */
 const StringFlagItem gpi_gphoto_port_type_map[] = {
 	{ "none",   GP_PORT_NONE },
 	{ "serial", GP_PORT_SERIAL },
diff --git a/libgphoto2_port/libgphoto2_port/gphoto2-port-log.c b/libgphoto2_port/libgphoto2_port/gphoto2-port-log.c
index f11afd084..bedc331ef 100644
--- a/libgphoto2_port/libgphoto2_port/gphoto2-port-log.c
+++ b/libgphoto2_port/libgphoto2_port/gphoto2-port-log.c
@@ -1,17 +1,20 @@
 /** \file
  *
- * Copyright © 2001 Lutz Müller <lutz@users.sf.net>
+ * \author Copyright 2001 Lutz Müller <lutz@users.sf.net>
  *
+ * \par License
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
  * License as published by the Free Software Foundation; either
  * version 2 of the License, or (at your option) any later version.
  *
+ * \par
  * This library is distributed in the hope that it will be useful, 
  * but WITHOUT ANY WARRANTY; without even the implied warranty of 
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Lesser General Public License for more details. 
  *
+ * \par
  * You should have received a copy of the GNU Lesser General Public
  * License along with this library; if not, write to the
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
@@ -54,17 +57,18 @@ static LogFunc *log_funcs = NULL;
 static unsigned int log_funcs_count = 0;
 
 /**
- * gp_log_add_func:
- * @level: a #GPLogLevel
- * @func: a #GPLogFunc
- * @data: data
+ * \brief Add a function to get logging information
+ *
+ * \param level a #GPLogLevel
+ * \param func a #GPLogFunc
+ * \param data data
  *
  * Adds a log function that will be called for each log message that is flagged
- * with a log level that appears in given log @level. This function returns
+ * with a log level that appears in given log level. This function returns
  * an id that you can use for removing the log function again (using
  * #gp_log_remove_func).
  *
- * Return value: an id or a gphoto2 error code
+ * \return an id or a gphoto2 error code
  **/
 int
 gp_log_add_func (GPLogLevel level, GPLogFunc func, void *data)
@@ -94,12 +98,12 @@ gp_log_add_func (GPLogLevel level, GPLogFunc func, void *data)
 }
 
 /**
- * gp_log_remove_func:
- * @id: an id (return value of #gp_log_add_func)
+ * \brief Remove a logging receiving function
+ * \param id an id (return value of #gp_log_add_func)
  *
- * Removes the log function with given @id.
+ * Removes the log function with given id.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_log_remove_func (int id)
@@ -113,31 +117,31 @@ gp_log_remove_func (int id)
 	return (GP_OK);
 }
 
-/*
+/**
  * Width of offset field in characters. Note that HEXDUMP_COMPLETE_LINE 
  * needs to be changed when this value is changed.
  */
 #define HEXDUMP_OFFSET_WIDTH 4
 
-/*
+/**
  * Distance between offset, hexdump and ascii blocks. Note that
  * HEXDUMP_COMPLETE_LINE needs to be changed when this value is changed.
  */
 #define HEXDUMP_BLOCK_DISTANCE 2
 
-/* Initial value for x "pointer" (for hexdump) */
+/** Initial value for x "pointer" (for hexdump) */
 #define HEXDUMP_INIT_X (HEXDUMP_OFFSET_WIDTH + HEXDUMP_BLOCK_DISTANCE)
 
-/* Initial value for y "pointer" (for ascii values) */
+/** Initial value for y "pointer" (for ascii values) */
 #define HEXDUMP_INIT_Y (HEXDUMP_INIT_X + 3 * 16 - 1 + HEXDUMP_BLOCK_DISTANCE)
 
-/* Used to switch to next line */
+/** Used to switch to next line */
 #define HEXDUMP_LINE_WIDTH (HEXDUMP_INIT_Y + 16)
 
-/* Used to put the '-' character in the middle of the hexdumps */
+/** Used to put the '-' character in the middle of the hexdumps */
 #define HEXDUMP_MIDDLE (HEXDUMP_INIT_X + 3 * 8 - 1)
 
-/*
+/**
  * We are lazy and do our typing only once. Please note that you have
  * to add/remove some lines when increasing/decreasing the values of 
  * HEXDUMP_BLOCK_DISTANCE and/or HEXDUMP_OFFSET_WIDTH.
@@ -156,12 +160,12 @@ gp_log_remove_func (int id)
         curline = curline + (HEXDUMP_LINE_WIDTH + 1);}
 
 /**
- * gp_log_data:
- * @domain: the domain
- * @data: the data to be logged
- * @size: the size of the @data
+ * \brief Log data
+ * \brief domain the domain
+ * \brief data the data to be logged
+ * \brief size the size of the data
  *
- * Takes the @data and creates a formatted hexdump string. If you would like
+ * Takes the data and creates a formatted hexdump string. If you would like
  * to log text messages, use #gp_log instead.
  **/
 void
@@ -237,13 +241,13 @@ gp_log_data (const char *domain, const char *data, unsigned int size)
 #undef HEXDUMP_OFFSET_WIDTH
 
 /**
- * gp_logv:
- * @level: gphoto2 log level
- * @domain: the domain
- * @format: the format
- * @args: the va_list corresponding to @format
+ * \brief Log a debug or error message with va_list
+ * \param level gphoto2 log level
+ * \param domain the domain
+ * \param format the format
+ * \param args the va_list corresponding to format
  *
- * Logs a message at the given log @level. You would normally use this
+ * Logs a message at the given log level. You would normally use this
  * function to log as yet unformatted strings. 
  **/
 void
@@ -270,14 +274,14 @@ gp_logv (GPLogLevel level, const char *domain, const char *format,
 }
 
 /**
- * gp_log:
- * @level: gphoto2 log level
- * @domain: the domain
- * @format: the format
- * @...:
+ * \brief Log a debug or error message
+ * \param level gphoto2 log level
+ * \param domain the log domain
+ * \param format a printf style format string
+ * \param ... the variable argumentlist for above format string
  *
- * Logs a message at the given log @level. You would normally use this
- * function to log strings.
+ * Logs a message at the given log level. You would normally use this
+ * function to log general debug output in a printf way.
  **/
 void
 gp_log (GPLogLevel level, const char *domain, const char *format, ...)
@@ -345,6 +349,9 @@ gp_log (GPLogLevel level, const char *domain, const char *format, ...)
 
 #ifdef _GPHOTO2_INTERNAL_CODE
 
+/** 
+ * \brief (Internal) translate a enumeration code to a string
+ */
 const char *
 gpi_enum_to_string(unsigned int _enum, 
 		   const StringFlagItem *map)
@@ -359,6 +366,9 @@ gpi_enum_to_string(unsigned int _enum,
 	return NULL;
 }
 
+/** 
+ * \brief (Internal) translate a string to an enumeration code
+ */
 int
 gpi_string_to_enum(const char *str,
 		   unsigned int *result,
diff --git a/libgphoto2_port/libgphoto2_port/gphoto2-port-portability.c b/libgphoto2_port/libgphoto2_port/gphoto2-port-portability.c
index bf429884d..3256b6fd3 100644
--- a/libgphoto2_port/libgphoto2_port/gphoto2-port-portability.c
+++ b/libgphoto2_port/libgphoto2_port/gphoto2-port-portability.c
@@ -1,4 +1,9 @@
-/** \file */
+/** \file
+ * \brief Various portability functions.
+ *
+ * This file contains various portability functions that
+ * make non UNIX (Windows) ports easier.
+ */
 
 #include "config.h"
 #include <stdio.h>
@@ -134,6 +139,14 @@ int gp_system_is_dir (const char *dirname) {
 
 #else
 
+/** 
+ * \brief mkdir UNIX functionality
+ * \param dirname directory to create
+ * 
+ * Creates a new directory.
+ *
+ * \return a gphoto error code
+ */
 int gp_system_mkdir (const char *dirname) {
 
         if (mkdir(dirname, 0700)<0)
@@ -141,6 +154,14 @@ int gp_system_mkdir (const char *dirname) {
         return (GP_OK);
 }
 
+/**
+ * \brief rmdir UNIX functionality
+ * \param dirname directory to remove
+ * 
+ * Removes a empty directory.
+ *
+ * \return a gphoto error code
+ */
 int gp_system_rmdir (const char *dirname) {
 
 	if (rmdir (dirname) < 0)
@@ -149,23 +170,67 @@ int gp_system_rmdir (const char *dirname) {
 	return (GP_OK);
 }
 
+/**
+ * \brief opendir UNIX functionality
+ * \param dirname directory to open
+ * 
+ * Opens a directory for readdir and later closedir operations, 
+ * to enumerate its contents.
+ *
+ * \return a directory handle for use in gp_system_readdir() and gp_system_closedir()
+ */
 gp_system_dir gp_system_opendir (const char *dirname) {
         return (opendir(dirname));
 }
 
+/**
+ * \brief readdir UNIX functionality
+ * \param d directory to enumerate
+ * 
+ * Reads one directory entry from the specified directory handle
+ * as returned from gp_system_opendir(). Use gp_system_filename()
+ * to extract the filename from the returned value.
+ *
+ * \return a new gp_system_dirent or NULL
+ */
 gp_system_dirent gp_system_readdir (gp_system_dir d) {
         return (readdir(d));
 }
 
+/**
+ * \brief retrieve UNIX filename out of a directory entry
+ * \param de directory entry as returned from gp_system_readdir()
+ * 
+ * Extracts a filename out of the passed directory entry.
+ *
+ * \return the filename of the directory entry
+ */
 const char *gp_system_filename (gp_system_dirent de) {
         return (de->d_name);
 }
 
+/**
+ * \brief closedir UNIX functionality
+ * \param dir directory to close
+ * 
+ * Closes a directory after readdir operations. 
+ *
+ * \return a gphoto error code
+ */
 int gp_system_closedir (gp_system_dir dir) {
         closedir(dir);
         return (GP_OK);
 }
 
+/**
+ * \brief check if passed filename is a file
+ * \param filename file name to check
+ * 
+ * Checks whether the passed in filename is
+ * a file and returns this as boolean.
+ *
+ * \return boolean flag whether passed filename is a file.
+ */
 int gp_system_is_file (const char *filename) {
         struct stat st;
 
@@ -174,6 +239,15 @@ int gp_system_is_file (const char *filename) {
         return (!S_ISDIR(st.st_mode));
 }
 
+/**
+ * \brief check if passed filename is a directory
+ * \param dirname file name to check
+ * 
+ * Checks whether the passed in dirname is
+ * a directory and returns this as boolean.
+ *
+ * \return boolean flag whether passed filename is a directory.
+ */
 int gp_system_is_dir (const char *dirname) {
         struct stat st;
 
diff --git a/libgphoto2_port/libgphoto2_port/gphoto2-port.c b/libgphoto2_port/libgphoto2_port/gphoto2-port.c
index 20481172e..6adc557d5 100644
--- a/libgphoto2_port/libgphoto2_port/gphoto2-port.c
+++ b/libgphoto2_port/libgphoto2_port/gphoto2-port.c
@@ -1,4 +1,4 @@
-/* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
+main/* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
 /** \file
  * 
  * \author Copyright 2001 Lutz Müller <lutz@users.sf.net>
@@ -60,11 +60,11 @@
  * This structure contains private data.
  **/
 struct _GPPortPrivateCore {
-	char error[2048];
+	char error[2048];	/**< Internal kept error message. */
 
-	GPPortInfo info;
-	GPPortOperations *ops;
-	lt_dlhandle lh;
+	GPPortInfo info;	/**< Internal port information of this port. */
+	GPPortOperations *ops;	/**< Internal port operations. */
+	lt_dlhandle lh;		/**< Internal libtool library handle. */
 };
 
 /**
@@ -74,7 +74,7 @@ struct _GPPortPrivateCore {
  *
  * After you called this function, 
  * you probably want to call #gp_port_set_info in order to make the newly
- * created @port functional.
+ * created port functional.
  *
  * \param port Pointer the #GPPort* pointer
  * \return a gphoto2 error code
@@ -266,7 +266,7 @@ gp_port_open (GPPort *port)
  * \brief Close a port.
  * \param port a #GPPort
  *
- * Closes a @port temporarily. It can afterwards be reopened using
+ * Closes a port temporarily. It can afterwards be reopened using
  * #gp_port_open.
  *
  * \return a gphoto2 error code
@@ -289,7 +289,7 @@ gp_port_close (GPPort *port)
  * \brief Free the port structure
  * \param port a #GPPort
  *
- * Closes the @port and frees the memory.
+ * Closes the port and frees the memory.
  *
  * \return a gphoto2 error code
  **/
@@ -493,7 +493,7 @@ gp_port_check_int_fast (GPPort *port, char *data, int size)
  * \param port a #GPPort
  * \param timeout the timeout
  *
- * Sets the @timeout of a @port. #gp_port_read will wait @timeout milliseconds
+ * Sets the timeout of a port. #gp_port_read will wait timeout milliseconds
  * for data. If no data will be received in that period, %GP_ERROR_TIMEOUT
  * will be returned.
  *
@@ -599,7 +599,7 @@ int gp_port_settings_set (GPPort *port, GPPortSettings settings)
  * \param port a #GPPort
  * \param settings pointer to the retrieved settings
  *
- * Retreives the current @settings of a port.
+ * Retreives the current settings of a port.
  *
  * \return a gphoto2 error code
  **/
@@ -781,7 +781,7 @@ gp_port_usb_find_device (GPPort *port, int idvendor, int idproduct)
  * \brief Find USB device by interface class
  *
  * \param port a GPPort
- * \param class the USB interface class
+ * \param mainclass the USB interface class
  * \param subclass the USB interface subclass
  * \param protocol the USB interface protocol
  *
@@ -1101,7 +1101,7 @@ gp_port_set_error (GPPort *port, const char *format, ...)
  * \brief Get verbose port error message
  * \param port a #GPPort
  *
- * Retrieves an error message from a @port. If you want to make sure that
+ * Retrieves an error message from a port. If you want to make sure that
  * you get correct error messages, you need to call #gp_port_set_error with
  * an error message of %NULL each time before calling another port-related
  * function of which you want to check the return value.