Documentation updates.

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

4 files changed, 256 insertions, 0 deletions

diff --git a/doc/api/tmpl/gphoto2-context.sgml b/doc/api/tmpl/gphoto2-context.sgml
new file mode 100644
index 000000000..ce94eb5a0
--- /dev/null
+++ b/doc/api/tmpl/gphoto2-context.sgml
@@ -0,0 +1,216 @@
+<!-- ##### SECTION Title ##### -->
+GPContext
+
+<!-- ##### SECTION Short_Description ##### -->
+The structure giving you control over operations
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+  This section describes how to monitor and control operations.
+</para>
+
+<para>
+  Operations that involve communication with digital cameras can 
+  take some time. For example, downloading an image over a slow serial
+  line can take several minutes. In order to be able to keep the frontend
+  responsive, to give the user the possibility to cancel operations, and in
+  order to be able to
+  report detailed error messages, #GPContext has been introduced.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### STRUCT GPContext ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gp_context_new ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION gp_context_ref ##### -->
+<para>
+
+</para>
+
+@context: 
+
+
+<!-- ##### FUNCTION gp_context_unref ##### -->
+<para>
+
+</para>
+
+@context: 
+
+
+<!-- ##### FUNCTION gp_context_set_progress_funcs ##### -->
+<para>
+
+</para>
+
+@context: 
+@start_func: 
+@update_func: 
+@stop_func: 
+@data: 
+
+
+<!-- ##### FUNCTION gp_context_set_cancel_func ##### -->
+<para>
+
+</para>
+
+@context: 
+@func: 
+@data: 
+
+
+<!-- ##### FUNCTION gp_context_set_question_func ##### -->
+<para>
+
+</para>
+
+@context: 
+@func: 
+@data: 
+
+
+<!-- ##### FUNCTION gp_context_set_message_func ##### -->
+<para>
+
+</para>
+
+@context: 
+@func: 
+@data: 
+
+
+<!-- ##### FUNCTION gp_context_set_idle_func ##### -->
+<para>
+
+</para>
+
+@context: 
+@func: 
+@data: 
+
+
+<!-- ##### FUNCTION gp_context_set_error_func ##### -->
+<para>
+
+</para>
+
+@context: 
+@func: 
+@data: 
+
+
+<!-- ##### FUNCTION gp_context_set_status_func ##### -->
+<para>
+
+</para>
+
+@context: 
+@func: 
+@data: 
+
+
+<!-- ##### FUNCTION gp_context_progress_start ##### -->
+<para>
+
+</para>
+
+@context: 
+@target: 
+@format: 
+@Varargs: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gp_context_progress_update ##### -->
+<para>
+
+</para>
+
+@context: 
+@id: 
+@current: 
+
+
+<!-- ##### FUNCTION gp_context_progress_stop ##### -->
+<para>
+
+</para>
+
+@context: 
+@id: 
+
+
+<!-- ##### FUNCTION gp_context_message ##### -->
+<para>
+
+</para>
+
+@context: 
+@format: 
+@Varargs: 
+
+
+<!-- ##### FUNCTION gp_context_status ##### -->
+<para>
+
+</para>
+
+@context: 
+@format: 
+@Varargs: 
+
+
+<!-- ##### FUNCTION gp_context_question ##### -->
+<para>
+
+</para>
+
+@context: 
+@format: 
+@Varargs: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gp_context_error ##### -->
+<para>
+
+</para>
+
+@context: 
+@format: 
+@Varargs: 
+
+
+<!-- ##### FUNCTION gp_context_idle ##### -->
+<para>
+
+</para>
+
+@context: 
+
+
+<!-- ##### FUNCTION gp_context_cancel ##### -->
+<para>
+
+</para>
+
+@context: 
+@Returns: 
+
+
diff --git a/libgphoto2/gphoto2-camera.c b/libgphoto2/gphoto2-camera.c
index 754d774ab..23b0a61e4 100644
--- a/libgphoto2/gphoto2-camera.c
+++ b/libgphoto2/gphoto2-camera.c
@@ -242,6 +242,7 @@ struct _CameraPrivateCore {
 /**
  * gp_camera_exit:
  * @camera: a #Camera
+ * @context: a #GPContext
  *
  * Closes a connection to the camera and therefore gives other application
  * the possibility to access the camera, too. It is recommended that you 
@@ -603,6 +604,7 @@ gp_camera_free (Camera *camera)
 /**
  * gp_camera_init:
  * @camera: a #camera
+ * @context: a #GPContext
  *
  * Initiates a connection to the camera. Before calling this function, the
  * @camera should be set up using #gp_camera_set_port_path or
@@ -767,6 +769,7 @@ gp_camera_init (Camera *camera, GPContext *context)
  * 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.
@@ -797,6 +800,7 @@ gp_camera_get_config (Camera *camera, CameraWidget **window, GPContext *context)
  * gp_camera_set_config:
  * @camera: a #Camera
  * @window: a #CameraWidget
+ * @context: a #GPContext
  *
  * Sets the configuration. Typically, a @window is retrieved using
  * #gp_camera_get_config and passed to this function in order to adjust
@@ -828,6 +832,7 @@ gp_camera_set_config (Camera *camera, CameraWidget *window, GPContext *context)
  * gp_camera_get_summary:
  * @camera: a #Camera
  * @summary: a #CameraText
+ * @context: a #GPContext
  *
  * Retrieves a camera @summary. This summary typically contains information
  * like manufacturer, pictures taken, or generally information that is
@@ -859,6 +864,7 @@ gp_camera_get_summary (Camera *camera, CameraText *summary, GPContext *context)
  * gp_camera_get_manual:
  * @camera: a #Camera
  * @manual: a #CameraText
+ * @context: a #GPContext
  *
  * Retrieves the @manual for given @camera. This manual typically contains
  * information about using the camera.
@@ -889,6 +895,7 @@ gp_camera_get_manual (Camera *camera, CameraText *manual, GPContext *context)
  * gp_camera_get_about:
  * @camera: a #Camera
  * @about: a #CameraText
+ * @context: a #GPContext
  *
  * Retrieves information about the camera driver. Typically, this information
  * contains name and address of the author, acknowledgements, etc.
@@ -920,6 +927,7 @@ gp_camera_get_about (Camera *camera, CameraText *about, GPContext *context)
  * @camera: a #Camera
  * @type: a #CameraCaptureType
  * @path: a #CameraFilePath
+ * @context: a #GPContext
  *
  * Captures an image, movie, or sound clip depending on the given @type.
  * The resulting file will be stored on the camera. The location gets stored
@@ -951,6 +959,7 @@ gp_camera_capture (Camera *camera, CameraCaptureType type,
  * gp_camera_capture_preview:
  * @camera: a #Camera
  * @file: a #CameraFile
+ * @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 
@@ -985,6 +994,7 @@ gp_camera_capture_preview (Camera *camera, CameraFile *file, GPContext *context)
  * @camera: a #Camera
  * @folder: a folder
  * @list: a #CameraList
+ * @context: a #GPContext
  *
  * Lists the files in supplied @folder.
  *
@@ -1014,6 +1024,7 @@ gp_camera_folder_list_files (Camera *camera, const char *folder,
  * @camera: a #Camera
  * @folder: a folder
  * @list: a #CameraList
+ * @context: a #GPContext
  *
  * Lists the folders in supplied @folder.
  *
@@ -1042,6 +1053,7 @@ gp_camera_folder_list_folders (Camera *camera, const char* folder,
  * gp_camera_folder_delete_all:
  * @camera: a #Camera
  * @folder: a folder
+ * @context: a #GPContext
  *
  * Deletes all files in a given @folder.
  *
@@ -1069,6 +1081,7 @@ gp_camera_folder_delete_all (Camera *camera, const char *folder,
  * @camera: a #Camera
  * @folder: a folder
  * @file: a #CameraFile
+ * @context: a #GPContext
  *
  * Uploads a file into given @folder.
  *
@@ -1097,6 +1110,7 @@ gp_camera_folder_put_file (Camera *camera, const char *folder,
  * @folder: a folder
  * @file: the name of the file
  * @info:
+ * @context: a #GPContext
  *
  * Retrieves information about a @file.
  *
@@ -1168,6 +1182,7 @@ gp_camera_file_get_info (Camera *camera, const char *folder,
  * @folder: a folder
  * @file: the name of a file
  * @info: the #CameraFileInfo
+ * @context: a #GPContext
  *
  * Sets some file properties like name or permissions.
  *
@@ -1195,6 +1210,7 @@ gp_camera_file_set_info (Camera *camera, const char *folder,
  * @file: the name of a file
  * @type: the #CameraFileType
  * @camera_file: a #CameraFile
+ * @context: a #GPContext
  *
  * Retrieves a @file from the @camera.
  *
@@ -1235,6 +1251,7 @@ gp_camera_file_get (Camera *camera, const char *folder, const char *file,
  * @camera: a #Camera
  * @folder: a folder
  * @file: the name of a file
+ * @context: a #GPContext
  *
  * Deletes the @file from a @folder.
  *
@@ -1262,6 +1279,7 @@ gp_camera_file_delete (Camera *camera, const char *folder, const char *file,
  * @camera: a #Camera
  * @folder: the location where to create the new directory
  * @name: the name of the directory to be created
+ * @context: a #GPContext
  *
  * Creates a new directory called @name in given @folder.
  *
@@ -1286,6 +1304,7 @@ gp_camera_folder_make_dir (Camera *camera, const char *folder,
  * @camera: a #Camera
  * @folder: the folder from which to remove the directory
  * @name: the name of the directory to be removed
+ * @context: a #GPContext
  *
  * Removes an (empty) directory called @name from the given @folder.
  *
diff --git a/libgphoto2/gphoto2-context.c b/libgphoto2/gphoto2-context.c
index 173da96a6..b14113eaf 100644
--- a/libgphoto2/gphoto2-context.c
+++ b/libgphoto2/gphoto2-context.c
@@ -26,6 +26,11 @@
 
 #include <gphoto2-port-log.h>
 
+/**
+ * GPContext:
+ *
+ * The internals of this structure are private.
+ **/
 struct _GPContext
 {
 	GPContextIdleFunc     idle_func;
diff --git a/libgphoto2/gphoto2-filesys.c b/libgphoto2/gphoto2-filesys.c
index 27e79e37c..d399bdc5b 100644
--- a/libgphoto2/gphoto2-filesys.c
+++ b/libgphoto2/gphoto2-filesys.c
@@ -549,6 +549,7 @@ gp_filesystem_folder_number (CameraFilesystem *fs, const char *folder,
  * @fs: a #CameraFilesystem
  * @folder: the folder where to put the file in
  * @filename: filename of the file
+ * @context: a #GPContext
  *
  * Tells the @fs that there is a file called @filename in folder 
  * called @folder. Usually, camera drivers will call this function after
@@ -699,6 +700,7 @@ gp_filesystem_delete_all_one_by_one (CameraFilesystem *fs, const char *folder,
  * gp_filesystem_delete_all
  * @fs: a #CameraFilesystem
  * @folder: the folder in which to delete all files
+ * @context: a #GPContext
  *
  * Deletes all files in the given @folder from the @fs. If the @fs has not
  * been supplied with a delete_all_func, it tries to delete the files
@@ -761,6 +763,7 @@ gp_filesystem_delete_all (CameraFilesystem *fs, const char *folder,
  * @fs: a #CameraFilesystem
  * @folder: a folder of which a file list should be generated
  * @list: a #CameraList where to put the list of files into
+ * @context: a #GPContext
  *
  * Lists the files in @folder using either cached values or (if there
  * aren't any) the file_list_func which (hopefully) has been previously
@@ -823,6 +826,7 @@ gp_filesystem_list_files (CameraFilesystem *fs, const char *folder,
  * @fs: a #CameraFilesystem
  * @folder: a folder
  * @list: a #CameraList where subfolders should be listed
+ * @context: a #GPContext
  *
  * Generates a list of subfolders of the supplied @folder either using 
  * cached values (if there are any) or the folder_list_func if it has been 
@@ -917,6 +921,7 @@ gp_filesystem_list_folders (CameraFilesystem *fs, const char *folder,
  * gp_filesystem_count:
  * @fs: a #CameraFilesystem
  * @folder: a folder in which to count the files
+ * @context: a #GPContext
  *
  * Counts the files in the @folder.
  *
@@ -942,6 +947,7 @@ gp_filesystem_count (CameraFilesystem *fs, const char *folder,
  * @fs: a #CameraFilesystem
  * @folder: a folder in which to delete the file
  * @filename: the name of the file to delete
+ * @context: a #GPContext
  *
  * If a delete_file_func has been supplied to the @fs, this function will
  * be called and, if this function returns without error, the file will be 
@@ -1002,6 +1008,7 @@ gp_filesystem_delete_file_noop (CameraFilesystem *fs, const char *folder,
  * @fs: a #CameraFilesystem
  * @folder: the folder in which the directory should be created
  * @name: the name of the directory to be created
+ * @context: a #GPContext
  *
  * Creates a new directory called @name in given @folder.
  *
@@ -1087,6 +1094,7 @@ gp_filesystem_remove_dir (CameraFilesystem *fs, const char *folder,
  * @fs: a #CameraFilesystem
  * @folder: the folder where to put the @file into
  * @file: the file
+ * @context: a #GPContext
  *
  * Uploads a file to the camera if a put_file_func has been previously 
  * supplied to the @fs. If the upload is successful, the file will get
@@ -1127,6 +1135,7 @@ gp_filesystem_put_file (CameraFilesystem *fs, const char *folder,
  * @folder: the folder where to look up the file with the @filenumber
  * @filenumber: the number of the file
  * @filename:
+ * @context: a #GPContext
  *
  * Looks up the @filename of file with given @filenumber in given @folder.
  * See gp_filesystem_number for exactly the opposite functionality.
@@ -1161,6 +1170,7 @@ gp_filesystem_name (CameraFilesystem *fs, const char *folder, int filenumber,
  * @fs: a #CameraFilesystem
  * @folder: the folder where to look for file called @filename
  * @filename: the file to look for
+ * @context: a #GPContext
  *
  * Looks for a file called @filename in the given @folder. See
  * gp_filesystem_name for exactly the opposite functionality.
@@ -1240,6 +1250,7 @@ gp_filesystem_scan (CameraFilesystem *fs, const char *folder,
  * @fs: a #CameraFilesystem
  * @filename: the name of the file to search in the @fs
  * @folder:
+ * @context: a #GPContext
  *
  * Searches a file called @filename in the @fs and returns the first 
  * occurrency. This functionality is needed for camera drivers that cannot
@@ -1461,6 +1472,7 @@ gp_filesystem_get_file_impl (CameraFilesystem *fs, const char *folder,
  * @filename: the name of the file to download
  * @type: the type of the file
  * @file:
+ * @context: a #GPContext
  *
  * Downloads the file called @filename from the @folder using the 
  * get_file_func if such a function has been previously supplied. If the 
@@ -1618,6 +1630,7 @@ gp_filesystem_set_info_funcs (CameraFilesystem *fs,
  * @folder:
  * @filename:
  * @info:
+ * @context: a #GPContext
  *
  * Return value: a gphoto2 error code.
  **/
@@ -1681,6 +1694,7 @@ gp_filesystem_get_info (CameraFilesystem *fs, const char *folder,
  * @fs: a #CameraFilesystem
  * @folder:
  * @file: a #CameraFile
+ * @context: a #GPContext
  *
  * Tells the @fs about a file. Typically, camera drivers will call this
  * function in case they get information about a file (i.e. preview) "for free"
@@ -1776,6 +1790,7 @@ gp_filesystem_set_file_noop (CameraFilesystem *fs, const char *folder,
  * @fs: a #CameraFilesystem
  * @folder:
  * @info:
+ * @context: a #GPContext
  *
  * In contrast to #gp_filesystem_set_info, #gp_filesystem_set_info_noop
  * will only change the file information in the @fs. Typically, camera
@@ -1810,6 +1825,7 @@ gp_filesystem_set_info_noop (CameraFilesystem *fs, const char *folder,
  * @folder:
  * @filename:
  * @info:
+ * @context: a #GPContext
  *
  * Return value: a gphoto2 error code.
  **/