added/tuned/updated doxygen docs

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

1 files changed, 175 insertions, 176 deletions

diff --git a/libgphoto2/gphoto2-camera.c b/libgphoto2/gphoto2-camera.c
index 372824564..07695013b 100644
--- a/libgphoto2/gphoto2-camera.c
+++ b/libgphoto2/gphoto2-camera.c
@@ -1,20 +1,22 @@
-/* gphoto2-camera.c
+/** \file gphoto2-camera.c
+ * \brief Implement Camera object representing a camera attached to the system.
  *
- * Copyright © 2000 Scott Fritzinger
- *
- * Contributions:
- * 	2001-2002: Lutz Müller <lutz@users.sf.net>
+ * \author Copyright © 2000 Scott Fritzinger
+ * \author 2001-2002: Lutz Müller <lutz@users.sf.net>
  *
+ * \par
  * 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,
@@ -253,19 +255,21 @@ struct _CameraPrivateCore {
 	unsigned int           timeout_ids_len;
 };
 
+
 /**
- * gp_camera_exit:
- * @camera: a #Camera
- * @context: a #GPContext
+ * \brief Close connection to camera.
+ * \param camera a Camera object
+ * \param context a GPContext object
+ * \return a gphoto2 error code.
  *
  * Closes a connection to the camera and therefore gives other application
- * the possibility to access the camera, too. It is recommended that you 
+ * the possibility to access the camera, too.
+ *
+ * It is recommended that you 
  * call this function when you currently don't need the camera. The camera
- * will get reinitialized by #gp_camera_init automatically if you try to 
+ * will get reinitialized by gp_camera_init() automatically if you try to 
  * access the camera again.
- *
- * Return value: a gphoto2 error code.
- **/
+ */
 int
 gp_camera_exit (Camera *camera, GPContext *context)
 {
@@ -310,14 +314,12 @@ gp_camera_exit (Camera *camera, GPContext *context)
 	return (GP_OK);
 }
 
+
 /**
- * gp_camera_new:
- * @camera:
- *
- * Allocates the memory for a #Camera.
- *
- * Return value: a gphoto2 error code
- **/
+ * \brief Allocates the memory for a Camera.
+ * \param camera The Camera:: object to initialize.
+ * \return a gphoto2 error code
+ */
 int
 gp_camera_new (Camera **camera)
 {
@@ -363,20 +365,20 @@ gp_camera_new (Camera **camera)
         return(GP_OK);
 }
 
+
 /**
- * gp_camera_set_abilities:
- * @camera: a #Camera
- * @abilities: the #CameraAbilities to be set
- *
- * Sets the camera abilities. You need to call this function before
- * calling #gp_camera_init the first time unless you want gphoto2 to autodetect 
- * cameras and choose the first detected one. By setting the @abilities, you
- * tell gphoto2 what model the @camera is and what camera driver should 
- * be used for accessing the @camera. You can get @abilities by calling
- * #gp_abilities_list_get_abilities.
- *
- * Return value: a gphoto2 error code
- **/
+ * \brief Sets the camera abilities. 
+ * \param camera: a #Camera
+ * \param abilities the #CameraAbilities to be set
+ * \return a gphoto2 error code
+ *
+ * You need to call this function before calling gp_camera_init() the
+ * first time unless you want gphoto2 to autodetect cameras and choose
+ * the first detected one. By setting the \c abilities, you 
+ * tell gphoto2 what model the \c camera is and what camera driver should 
+ * be used for accessing the \c camera. You can get \c abilities by calling
+ * gp_abilities_list_get_abilities().
+ */
 int
 gp_camera_set_abilities (Camera *camera, CameraAbilities abilities)
 {
@@ -397,15 +399,13 @@ gp_camera_set_abilities (Camera *camera, CameraAbilities abilities)
 	return (GP_OK);
 }
 
+
 /**
- * gp_camera_get_abilities:
- * @camera: a #Camera
- * @abilities:
- *
- * Retrieves the @abilities of the @camera. 
- *
- * Return value: a gphoto2 error code
- **/
+ * \brief Retrieve the \c abilities of the \c camera. 
+ * \param camera a #Camera
+ * \param abilities
+ * \return a gphoto2 error code
+ */
 int
 gp_camera_get_abilities (Camera *camera, CameraAbilities *abilities)
 {
@@ -416,6 +416,7 @@ gp_camera_get_abilities (Camera *camera, CameraAbilities *abilities)
 	return (GP_OK);
 }
 
+
 int
 gp_camera_get_port_info (Camera *camera, GPPortInfo *info)
 {
@@ -426,6 +427,7 @@ gp_camera_get_port_info (Camera *camera, GPPortInfo *info)
 	return (GP_OK);
 }
 
+
 int
 gp_camera_set_port_info (Camera *camera, GPPortInfo info)
 {
@@ -445,21 +447,21 @@ gp_camera_set_port_info (Camera *camera, GPPortInfo info)
 	return (GP_OK);
 }
 
+
 /**
- * gp_camera_set_port_speed:
- * @camera: a #Camera
- * @speed: the speed
+ * \brief Set the camera speed.
+ * \param camera a Camera
+ * \param speed the speed
+ * \return a gphoto2 error code
  *
- * Sets the speed. This function is typically used prior first initialization 
+ * This function is typically used prior first initialization 
  * using #gp_camera_init for debugging purposes. Normally, a camera driver
  * will try to figure out the current speed of the camera and set the speed
  * to the optimal one automatically. Note that this function only works with 
  * serial ports. In other words, you have to set the camera's port to a 
  * serial one (using #gp_camera_set_port_path or #gp_camera_set_port_name)
  * prior calling this function.
- *
- * Return value: a gphoto2 error code
- **/
+ */
 int
 gp_camera_set_port_speed (Camera *camera, int speed)
 {
@@ -494,14 +496,12 @@ gp_camera_set_port_speed (Camera *camera, int speed)
 	return (GP_OK);
 }
 
+
 /** 
- * gp_camera_get_port_speed:
- * @camera: a #Camera
- *
- * Retrieves the current speed.
- *
- * Return value: The current speed or a gphoto2 error code
- **/
+ * \brief Retrieve the current speed.
+ * \param camera a Camera
+ * \return The current speed or a gphoto2 error code
+ */
 int
 gp_camera_get_port_speed (Camera *camera)
 {
@@ -510,14 +510,12 @@ gp_camera_get_port_speed (Camera *camera)
 	return (camera->pc->speed);
 }
 
+
 /**
- * gp_camera_ref:
- * @camera: a #Camera
- *
- * Increments the reference count of a @camera.
- *
- * Return value: a gphoto2 error code
- **/
+ * \brief Increment the reference count of a @camera.
+ * \param camera a Camera
+ * \return a gphoto2 error code
+ */
 int
 gp_camera_ref (Camera *camera)
 {
@@ -528,15 +526,15 @@ gp_camera_ref (Camera *camera)
 	return (GP_OK);
 }
 
+
 /**
- * gp_camera_unref:
- * @camera: a #Camera
- *
- * Decrements the reference count of a @camera. If the reference count 
- * reaches %0, the @camera will be freed automatically.
+ * \brief Decrements the reference count of a Camera.
+ * \param camera a #Camera
+ * \return a gphoto2 error code
  *
- * Return value: a gphoto2 error code
- **/
+ * If the reference count reaches %0, the \c camera will be freed 
+ * automatically.
+ */
 int
 gp_camera_unref (Camera *camera)
 {
@@ -561,15 +559,15 @@ gp_camera_unref (Camera *camera)
 	return (GP_OK);
 }
 
+
 /**
- * gp_camera_free:
- * @camera: a #Camera
+ * \brief Free the \c camera.
+ * \param camera a Camera
+ * \return a gphoto2 error code
  *
- * Frees the camera. This function should never be used. Please use
- * #gp_camera_unref instead.
- *
- * Return value: a gphoto2 error code
- **/
+ * \deprecated 
+ * This function should never be used. Please use gp_camera_unref() instead.
+ */
 int
 gp_camera_free (Camera *camera)
 {
@@ -612,21 +610,21 @@ gp_camera_free (Camera *camera)
 	return (GP_OK);
 }
 
+
 /**
- * gp_camera_init:
- * @camera: a #camera
- * @context: a #GPContext
+ * \brief Initiate a connection to the \c camera. 
+ * \param camera a camera
+ * \param context a GPContext
+ * \return a gphoto2 error code
  *
- * Initiates a connection to the camera. Before calling this function, the
+ * Before calling this function, the
  * @camera should be set up using #gp_camera_set_port_path or
  * #gp_camera_set_port_name and #gp_camera_set_abilities. If that has been
  * omitted, gphoto2 tries to autodetect any cameras and chooses the first one
  * if any cameras are found. It is generally a good idea to call
  * #gp_camera_exit after transactions have been completed in order to give
  * other applications the chance to access the camera, too.
- *
- * Return value: a gphoto2 error code
- **/
+ */
 int
 gp_camera_init (Camera *camera, GPContext *context)
 {
@@ -767,17 +765,16 @@ gp_camera_init (Camera *camera, GPContext *context)
 	return (GP_OK);
 }
 
+
 /**
- * gp_camera_get_config:
- * @camera: a #Camera
- * @window:
- * @context: a #GPContext
- *
- * Retrieves a configuration @window for the @camera. This window can be
- * used for construction of a configuration dialog.
+ * \brief Retrieve a configuration \c window for the \c camera.
+ * \param camera a Camera
+ * \param window a CameraWidget
+ * \param context a GPContext
+ * \return gphoto2 error code
  *
- * Return value: a gphoto2 error code
- **/
+ * This \c window can be used for construction of a configuration dialog.
+ */
 int
 gp_camera_get_config (Camera *camera, CameraWidget **window, GPContext *context)
 {
@@ -798,6 +795,7 @@ gp_camera_get_config (Camera *camera, CameraWidget **window, GPContext *context)
 	return (GP_OK);
 }
 
+
 /**
  * gp_camera_set_config:
  * @camera: a #Camera
@@ -808,7 +806,7 @@ gp_camera_get_config (Camera *camera, CameraWidget **window, GPContext *context)
  * #gp_camera_get_config and passed to this function in order to adjust
  * the settings on the camera.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_camera_set_config (Camera *camera, CameraWidget *window, GPContext *context)
@@ -840,7 +838,7 @@ gp_camera_set_config (Camera *camera, CameraWidget *window, GPContext *context)
  * like manufacturer, pictures taken, or generally information that is
  * not configurable.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_camera_get_summary (Camera *camera, CameraText *summary, GPContext *context)
@@ -871,7 +869,7 @@ gp_camera_get_summary (Camera *camera, CameraText *summary, GPContext *context)
  * Retrieves the @manual for given @camera. This manual typically contains
  * information about using the camera.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_camera_get_manual (Camera *camera, CameraText *manual, GPContext *context)
@@ -902,7 +900,7 @@ gp_camera_get_manual (Camera *camera, CameraText *manual, GPContext *context)
  * Retrieves information about the camera driver. Typically, this information
  * contains name and address of the author, acknowledgements, etc.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_camera_get_about (Camera *camera, CameraText *about, GPContext *context)
@@ -935,7 +933,7 @@ gp_camera_get_about (Camera *camera, CameraText *about, GPContext *context)
  * The resulting file will be stored on the camera. The location gets stored
  * in @path. The file can then be downloaded using #gp_camera_file_get.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_camera_capture (Camera *camera, CameraCaptureType type,
@@ -959,15 +957,15 @@ gp_camera_capture (Camera *camera, CameraCaptureType type,
 
 /**
  * gp_camera_capture_preview:
- * @camera: a #Camera
- * @file: a #CameraFile
- * @context: a #GPContext
+ * \param camera: a #Camera
+ * \param file: a #CameraFile
+ * \param context: a #GPContext
  *
  * Captures a preview that won't be stored on the camera but returned in 
  * supplied @file. For example, you could use #gp_capture_preview for 
  * taking some sample pictures before calling #gp_capture.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_camera_capture_preview (Camera *camera, CameraFile *file, GPContext *context)
@@ -993,14 +991,14 @@ gp_camera_capture_preview (Camera *camera, CameraFile *file, GPContext *context)
 
 /**
  * gp_camera_folder_list_files:
- * @camera: a #Camera
- * @folder: a folder
- * @list: a #CameraList
- * @context: a #GPContext
+ * \param camera: a #Camera
+ * \param folder: a folder
+ * \param list: a #CameraList
+ * \param context: a #GPContext
  *
  * Lists the files in supplied @folder.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_camera_folder_list_files (Camera *camera, const char *folder, 
@@ -1023,14 +1021,14 @@ gp_camera_folder_list_files (Camera *camera, const char *folder,
 
 /**
  * gp_camera_folder_list_folders:
- * @camera: a #Camera
- * @folder: a folder
- * @list: a #CameraList
- * @context: a #GPContext
+ * \param camera: a #Camera
+ * \param folder: a folder
+ * \param list: a #CameraList
+ * \param context: a #GPContext
  *
  * Lists the folders in supplied @folder.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_camera_folder_list_folders (Camera *camera, const char* folder, 
@@ -1053,13 +1051,13 @@ gp_camera_folder_list_folders (Camera *camera, const char* folder,
 
 /**
  * gp_camera_folder_delete_all:
- * @camera: a #Camera
- * @folder: a folder
- * @context: a #GPContext
+ * \param camera: a #Camera
+ * \param folder: a folder
+ * \param context: a #GPContext
  *
  * Deletes all files in a given @folder.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_camera_folder_delete_all (Camera *camera, const char *folder,
@@ -1080,14 +1078,14 @@ gp_camera_folder_delete_all (Camera *camera, const char *folder,
 
 /**
  * gp_camera_folder_put_file:
- * @camera: a #Camera
- * @folder: a folder
- * @file: a #CameraFile
- * @context: a #GPContext
+ * \param camera: a #Camera
+ * \param folder: a folder
+ * \param file: a #CameraFile
+ * \param context: a #GPContext
  *
  * Uploads a file into given @folder.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_camera_folder_put_file (Camera *camera, const char *folder,
@@ -1108,15 +1106,15 @@ gp_camera_folder_put_file (Camera *camera, const char *folder,
 
 /**
  * gp_camera_file_get_info:
- * @camera: a #Camera
- * @folder: a folder
- * @file: the name of the file
- * @info:
- * @context: a #GPContext
+ * \param camera: a #Camera
+ * \param folder: a folder
+ * \param file: the name of the file
+ * \param info:
+ * \param context: a #GPContext
  *
  * Retrieves information about a @file.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_camera_file_get_info (Camera *camera, const char *folder, 
@@ -1180,15 +1178,15 @@ gp_camera_file_get_info (Camera *camera, const char *folder,
 
 /**
  * gp_camera_file_set_info:
- * @camera: a #Camera
- * @folder: a folder
- * @file: the name of a file
- * @info: the #CameraFileInfo
- * @context: a #GPContext
+ * \param camera: a #Camera
+ * \param folder: a folder
+ * \param file: the name of a file
+ * \param info: the #CameraFileInfo
+ * \param context: a #GPContext
  *
  * Sets some file properties like name or permissions.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_camera_file_set_info (Camera *camera, const char *folder, 
@@ -1207,16 +1205,16 @@ gp_camera_file_set_info (Camera *camera, const char *folder,
 
 /**
  * gp_camera_file_get:
- * @camera: a #Camera
- * @folder: a folder
- * @file: the name of a file
- * @type: the #CameraFileType
- * @camera_file: a #CameraFile
- * @context: a #GPContext
+ * \param camera: a #Camera
+ * \param folder: a folder
+ * \param file: the name of a file
+ * \param type: the #CameraFileType
+ * \param camera_file: a #CameraFile
+ * \param context: a #GPContext
  *
  * Retrieves a @file from the @camera.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int 
 gp_camera_file_get (Camera *camera, const char *folder, const char *file,
@@ -1250,14 +1248,14 @@ gp_camera_file_get (Camera *camera, const char *folder, const char *file,
 
 /**
  * gp_camera_file_delete:
- * @camera: a #Camera
- * @folder: a folder
- * @file: the name of a file
- * @context: a #GPContext
+ * \param camera: a #Camera
+ * \param folder: a folder
+ * \param file: the name of a file
+ * \param context: a #GPContext
  *
  * Deletes the @file from a @folder.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_camera_file_delete (Camera *camera, const char *folder, const char *file,
@@ -1278,14 +1276,14 @@ gp_camera_file_delete (Camera *camera, const char *folder, const char *file,
 
 /**
  * gp_camera_folder_make_dir:
- * @camera: a #Camera
- * @folder: the location where to create the new directory
- * @name: the name of the directory to be created
- * @context: a #GPContext
+ * \param camera: a #Camera
+ * \param folder: the location where to create the new directory
+ * \param name: the name of the directory to be created
+ * \param context: a #GPContext
  *
  * Creates a new directory called @name in given @folder.
  *
- * Return value: a gphoto2 error code
+ * \return a gphoto2 error code
  **/
 int
 gp_camera_folder_make_dir (Camera *camera, const char *folder,
@@ -1303,15 +1301,15 @@ gp_camera_folder_make_dir (Camera *camera, const char *folder,
 
 /**
  * gp_camera_folder_remove_dir:
- * @camera: a #Camera
- * @folder: the folder from which to remove the directory
- * @name: the name of the directory to be removed
- * @context: a #GPContext
+ * \param camera: a #Camera
+ * \param folder: the folder from which to remove the directory
+ * \param name: the name of the directory to be removed
+ * \param context: a #GPContext
  *
  * Removes an (empty) directory called @name from the given @folder.
  *
- * Return value: a gphoto2 error code
- **/
+ * \return a gphoto2 error code
+ */
 int
 gp_camera_folder_remove_dir (Camera *camera, const char *folder,
 			     const char *name, GPContext *context)
@@ -1328,17 +1326,17 @@ gp_camera_folder_remove_dir (Camera *camera, const char *folder,
 
 /**
  * gp_camera_set_timeout_funcs:
- * @camera: a #Camera
- * @start_func:
- * @stop_func:
- * @data:
+ * \param camera a Camera
+ * \param start_func
+ * \param stop_func
+ * \param data
  *
  * If your frontend has something like idle loops, it is recommended you
  * use #gp_camera_set_timeout_funcs in order to give the camera driver the
  * possibility to keep up the connection to the camera.
  *
- * Return value: a gphoto2 error code
- **/
+ * \return a gphoto2 error code
+ */
 void
 gp_camera_set_timeout_funcs (Camera *camera, CameraTimeoutStartFunc start_func,
 			     CameraTimeoutStopFunc stop_func,
@@ -1352,19 +1350,19 @@ gp_camera_set_timeout_funcs (Camera *camera, CameraTimeoutStartFunc start_func,
 	camera->pc->timeout_data = data;
 }
 
+
 /**
  * gp_camera_start_timeout:
- * @camera: a #Camera
- * @timeout: the number of seconds that should pass between each call to
- * 	     @func
- * @func: the function that should be called each @timeout seconds
+ * \param camera a #Camera
+ * \param timeout number of seconds that should pass between each call to
+ * 	     \c func
+ * \param func the function that should be called each \c timeout seconds
+ * \return The id of the background process or a gphoto2 error code
  *
- * This function should be called by the camera driver during #camera_init
+ * This function should be called by the camera driver during camera_init()
  * if the camera needs to be sent messages periodically in order to prevent
- * it to shut down.
- *
- * Return value: The id of the background process or a gphoto2 error code
- **/
+ * it from shutting down.
+ */
 int
 gp_camera_start_timeout (Camera *camera, unsigned int timeout,
 			 CameraTimeoutFunc func)
@@ -1398,15 +1396,16 @@ gp_camera_start_timeout (Camera *camera, unsigned int timeout,
 	return (id);
 }
 
+
 /**
- * gp_camera_stop_timeout:
- * @camera: a #Camera
- * @id: the id of the background process previously returned by 
- * 	#gp_camera_start_timeout
+ * \brief Stop periodic calls to keepalive function.
+ * \param camera a #Camera
+ * \param id the id of the background process previously returned by 
+ * 	gp_camera_start_timeout()
  *
  * Call this function in the camera driver if you want to stop a periodic
- * call to a function that has been started using #gp_camera_start_timeout.
- **/
+ * call to a function that has been started using gp_camera_start_timeout().
+ */
 void
 gp_camera_stop_timeout (Camera *camera, unsigned int id)
 {