Developers documentation updated.

2007-04-20  Iñigo Martínez  <inigomartinez@gmail.com>

	* shell/ev-application.c:
	* shell/ev-job-queue.c:
	* shell/ev-metadata-manager.c:
	* shell/ev-stock-icons.c:
	* shell/ev-window.c:
	* shell/main.c:
	
	Developers documentation updated.


svn path=/trunk/; revision=2410

6 files changed, 270 insertions, 1 deletions

diff --git a/shell/ev-application.c b/shell/ev-application.c
index 53d284f..2ce43c0 100644
--- a/shell/ev-application.c
+++ b/shell/ev-application.c
@@ -101,6 +101,13 @@ ev_application_register_service (EvApplication *application)
 }
 #endif /* ENABLE_DBUS */
 
+/**
+ * ev_application_get_instance:
+ *
+ * Checks for #EvApplication instance, if it doesn't exist it does create it.
+ *
+ * Returns: an instance of the #EvApplication data.
+ */
 EvApplication *
 ev_application_get_instance (void)
 {
@@ -161,6 +168,15 @@ init_session (EvApplication *application)
 			  G_CALLBACK (removed_from_session), application);
 }
 
+/**
+ * ev_display_open_if_needed:
+ * @name: the name of the display to be open if it's needed.
+ *
+ * Search among all the open displays if any of them have the same name as the
+ * passed name. If the display isn't found it tries the open it.
+ *
+ * Returns: a #GdkDisplay of the display with the passed name.
+ */
 static GdkDisplay *
 ev_display_open_if_needed (const gchar *name)
 {
@@ -184,6 +200,17 @@ ev_display_open_if_needed (const gchar *name)
 	return display != NULL ? display : gdk_display_open (name);
 }
 
+/**
+ * get_screen_from_args:
+ * @args: a #GHashTable with data passed to the application.
+ *
+ * Looks for the screen in the display available in the hash table passed to the
+ * application. If the display isn't opened, it's opened and the #GdkScreen
+ * assigned to the screen in that display returned.
+ *
+ * Returns: the #GdkScreen assigned to the screen on the display indicated by
+ *          the data on the #GHashTable.
+ */
 static GdkScreen *
 get_screen_from_args (GHashTable *args)
 {
@@ -212,6 +239,16 @@ get_screen_from_args (GHashTable *args)
 	return screen;
 }
 
+/**
+ * get_window_run_mode_from_args:
+ * @args: a #GHashTable with data passed to the application.
+ *
+ * It does look if the mode option has been passed from command line, using it
+ * as the window run mode, otherwise the run mode will be the normal mode.
+ *
+ * Returns: The window run mode passed from command line or
+ *          EV_WINDOW_MODE_NORMAL in other case.
+ */
 static EvWindowRunMode
 get_window_run_mode_from_args (GHashTable *args)
 {
@@ -228,6 +265,16 @@ get_window_run_mode_from_args (GHashTable *args)
 	return mode;
 }
 
+/**
+ * get_destination_from_args:
+ * @args: a #GHashTable with data passed to the application.
+ *
+ * It does look for the page-label argument parsed from the command line and
+ * if it does exist, it returns an #EvLinkDest.
+ *
+ * Returns: An #EvLinkDest to page-label if it has been passed from the command
+ *          line, NULL in other case.
+ */
 static EvLinkDest *
 get_destination_from_args (GHashTable *args)
 {
@@ -247,6 +294,16 @@ get_destination_from_args (GHashTable *args)
 	return dest;
 }
 
+/**
+ * get_unlink_temp_file_from_args:
+ * @args: a #GHashTable with data passed to the application.
+ *
+ * It does look if the unlink-temp-file option has been passed from the command
+ * line returning it's boolean representation, otherwise it does return %FALSE.
+ *
+ * Returns: the boolean representation of the unlink-temp-file value or %FALSE
+ *          in other case.
+ */
 static gboolean
 get_unlink_temp_file_from_args (GHashTable *args)
 {
@@ -263,6 +320,19 @@ get_unlink_temp_file_from_args (GHashTable *args)
 	return unlink_temp_file;
 }
 
+/**
+ * ev_application_open_window:
+ * @application: The instance of the application.
+ * @args: A #GHashTable with the arguments data.
+ * @timestamp: Current time value.
+ * @error: The #GError facility.
+ * 
+ * Creates a new window and if the args are available, it's not NULL, it gets
+ * the screen from them and assigns the just created window to it. At last it
+ * does show it.
+ *
+ * Returns: %TRUE.
+ */
 gboolean
 ev_application_open_window (EvApplication  *application,
 			    GHashTable     *args,
@@ -287,6 +357,16 @@ ev_application_open_window (EvApplication  *application,
 	return TRUE;
 }
 
+/**
+ * ev_application_get_empty_window:
+ * @application: The instance of the application.
+ * @screen: The screen where the empty window will be search.
+ *
+ * It does look if there is any empty window in the indicated screen.
+ *
+ * Returns: The first empty #EvWindow in the passed #GdkScreen or NULL in other
+ *          case.
+ */
 static EvWindow *
 ev_application_get_empty_window (EvApplication *application,
 				 GdkScreen     *screen)
@@ -310,6 +390,18 @@ ev_application_get_empty_window (EvApplication *application,
 	return empty_window;
 }
 
+/**
+ * ev_application_get_uri_window:
+ * @application: The instance of the application.
+ * @uri: The uri to be opened.
+ *
+ * It looks in the list of the windows for the one with the document represented
+ * by the passed uri on it. If the window is empty or the document isn't present
+ * on any window, it will return NULL.
+ *
+ * Returns: The #EvWindow where the document represented by the passed uri is
+ *          shown, NULL in other case.
+ */
 static EvWindow *
 ev_application_get_uri_window (EvApplication *application, const char *uri)
 {
@@ -336,6 +428,16 @@ ev_application_get_uri_window (EvApplication *application, const char *uri)
 	return uri_window;
 }
 
+/**
+ * ev_application_open_uri_at_dest:
+ * @application: The instance of the application.
+ * @uri: The uri to be opened.
+ * @screen: Thee screen where the link will be shown.
+ * @dest: The #EvLinkDest of the document.
+ * @mode: The run mode of the window.
+ * @unlink_temp_file: The unlink_temp_file option value.
+ * @timestamp: Current time value.
+ */
 void
 ev_application_open_uri_at_dest (EvApplication  *application,
 				 const char     *uri,
@@ -400,6 +502,14 @@ ev_application_open_uri_at_dest (EvApplication  *application,
 				      timestamp);
 }
 
+/**
+ * ev_application_open_uri:
+ * @application: The instance of the application.
+ * @uri: The uri to be opened
+ * @args: A #GHashTable with the arguments data.
+ * @timestamp: Current time value.
+ * @error: The #GError facility.
+ */
 gboolean
 ev_application_open_uri (EvApplication  *application,
 			 const char     *uri,
@@ -516,6 +626,14 @@ ev_application_init (EvApplication *ev_application)
 #endif /* HAVE_GTK_RECENT */
 }
 
+/**
+ * ev_application_get_windows:
+ * @application: The instance of the application.
+ *
+ * It creates a list of the top level windows.
+ *
+ * Returns: A #GList of the top level windows.
+ */
 GList *
 ev_application_get_windows (EvApplication *application)
 {
diff --git a/shell/ev-job-queue.c b/shell/ev-job-queue.c
index d2733d6..bd7b86c 100644
--- a/shell/ev-job-queue.c
+++ b/shell/ev-job-queue.c
@@ -52,6 +52,14 @@ add_job_to_async_queue (GQueue *queue, EvJob *job)
 	g_queue_push_tail (queue, job);
 }
 
+/**
+ * add_job_to_queue_locked:
+ * @queue: a #GQueue where the #EvJob will be added.
+ * @job: an #EvJob to be added to the specified #GQueue.
+ *
+ * Add the #EvJob to the specified #GQueue and woke up the ev_render_thread who
+ * is waiting for render_cond.
+ */
 static void
 add_job_to_queue_locked (GQueue *queue,
 			 EvJob  *job)
@@ -61,6 +69,14 @@ add_job_to_queue_locked (GQueue *queue,
 	g_cond_broadcast (render_cond);
 }
 
+/**
+ * notify_finished:
+ * @job: the object that signal will be reseted.
+ *
+ * It does emit the job finished signal and returns %FALSE.
+ *
+ * Returns: %FALSE.
+ */
 static gboolean
 notify_finished (GObject *job)
 {
@@ -69,6 +85,13 @@ notify_finished (GObject *job)
 	return FALSE;
 }
 
+/**
+ * job_finished_cb:
+ * @job: the #EvJob that has been handled.
+ *
+ * It does finish the job last work and look if there is any more job to be
+ * handled.
+ */
 static void
 job_finished_cb (EvJob *job)
 {
@@ -77,6 +100,14 @@ job_finished_cb (EvJob *job)
 	ev_job_queue_run_next ();
 }
 
+/**
+ * handle_job:
+ * @job: the #EvJob to be handled.
+ *
+ * First, it does check if the job is async and then it does attend it if
+ * possible giving a failed assertion otherwise. If the job isn't async it does
+ * attend it and notify that the job has been finished.
+ */
 static void
 handle_job (EvJob *job)
 {
@@ -114,6 +145,24 @@ handle_job (EvJob *job)
 	}
 }
 
+/**
+ * search_for_jobs_unlocked:
+ *
+ * Check if there is any job at the synchronized queues and return any existing
+ * job in them taking in account the next priority:
+ *
+ *  render_queue_high       >
+ *  thumbnail_queue_high    >
+ *  render_queue_low        >
+ *  links_queue             >
+ *  load_queue              >
+ *  thumbnail_queue_low     >
+ *  fonts_queue             >
+ *  print_queue             >
+ *
+ * Returns: an available #EvJob in the queues taking in account stablished queue
+ *          priorities.
+ */
 static EvJob *
 search_for_jobs_unlocked (void)
 {
@@ -154,6 +203,15 @@ search_for_jobs_unlocked (void)
 	return NULL;
 }
 
+/**
+ * no_jobs_available_unlocked:
+ *
+ * Looks if there is any job at render, links, load, thumbnail. fonts and print
+ * queues.
+ *
+ * Returns: %TRUE if the render, links, load, thumbnail, fonts and print queues
+ *          are empty, %FALSE in other case.
+ */
 static gboolean
 no_jobs_available_unlocked (void)
 {
@@ -168,6 +226,16 @@ no_jobs_available_unlocked (void)
 }
 
 /* the thread mainloop function */
+/**
+ * ev_render_thread:
+ * @data: data passed to the thread.
+ *
+ * The thread mainloop function. It does wait for any available job in synced
+ * queues to handle it.
+ *
+ * Returns: the return value of the thread, which will be returned by
+ *          g_thread_join().
+ */
 static gpointer
 ev_render_thread (gpointer data)
 {
@@ -192,6 +260,12 @@ ev_render_thread (gpointer data)
 
 }
 
+/**
+ * ev_job_queue_run_next:
+ *
+ * It does look for any job on the render high priority queue first and after
+ * in the render low priority one, and then it does handle it.
+ */
 static void
 ev_job_queue_run_next (void)
 {
@@ -211,6 +285,12 @@ ev_job_queue_run_next (void)
 }
 
 /* Public Functions */
+/**
+ * ev_job_queue_init:
+ *
+ * Creates a new cond, new mutex, a thread for evince job handling and inits
+ * every queue.
+ */
 void
 ev_job_queue_init (void)
 {
diff --git a/shell/ev-metadata-manager.c b/shell/ev-metadata-manager.c
index c3fc422..0dba983 100644
--- a/shell/ev-metadata-manager.c
+++ b/shell/ev-metadata-manager.c
@@ -72,6 +72,12 @@ static gboolean ev_metadata_manager_save (gpointer data);
 
 static EvMetadataManager *ev_metadata_manager = NULL;
 
+/**
+ * item_free:
+ * @data: a pointer to a #Item data
+ *
+ * It does free the values on the #GHashTable where data points.
+ */
 static void
 item_free (gpointer data)
 {
@@ -87,6 +93,16 @@ item_free (gpointer data)
 	g_free (item);
 }
 
+/**
+ * ev_metadata_manager_init:
+ *
+ * Creates an EvMetadataManager with default values.
+ *
+ *  values_loaded   ->  %FALSE.
+ *  modified        ->  %FALSE.
+ *  timeout_id      ->  the id of the event source.
+ *  items           ->  a new full empty #GHashTable.
+ */
 void
 ev_metadata_manager_init (void)
 {
@@ -380,7 +396,7 @@ ev_metadata_manager_set_last (const gchar *key,
 }
 				 
 /**
- * ev_metadata_manager_set:
+ * ev_metadata_manager_get:
  * @uri: Uri to set data for, if @NULL, we return default value
  * @key: Key to set uri
  * @value: GValue struct filled up with value
diff --git a/shell/ev-stock-icons.c b/shell/ev-stock-icons.c
index f2d059b..799878d 100644
--- a/shell/ev-stock-icons.c
+++ b/shell/ev-stock-icons.c
@@ -43,6 +43,11 @@ static const EvStockIcon stock_icons [] = {
 	{ EV_STOCK_ROTATE_RIGHT,     "object-rotate-right"},
 };
 
+/**
+ * ev_stock_icons_init:
+ *
+ * Creates a new icon factory, adding the base stock icons to it.
+ */
 void
 ev_stock_icons_init (void)
 {
diff --git a/shell/ev-window.c b/shell/ev-window.c
index 4d76b6f..532aa4e 100644
--- a/shell/ev-window.c
+++ b/shell/ev-window.c
@@ -606,6 +606,16 @@ update_sizing_buttons (EvWindow *window)
 	}
 }
 
+/**
+ * ev_window_is_empty:
+ * @ev_window: The instance of the #EvWindow.
+ *
+ * It does look if there is any document loaded or if there is any job to load
+ * a document.
+ *
+ * Returns: %TRUE if there isn't any document loaded or any any documente to be
+ *          loaded, %FALSE in other case.
+ */
 gboolean
 ev_window_is_empty (const EvWindow *ev_window)
 {
@@ -1340,12 +1350,27 @@ ev_window_load_job_cb  (EvJobLoad *job,
 	return;
 }
 
+/**
+ * ev_window_get_uri:
+ * @ev_window: The instance of the #EvWindow.
+ *
+ * It returns the uri of the document showed in the #EvWindow.
+ *
+ * Returns: the uri of the document showed in the #EvWindow.
+ */
 const char *
 ev_window_get_uri (EvWindow *ev_window)
 {
 	return ev_window->priv->uri;
 }
 
+/**
+ * ev_window_close_dialogs:
+ * @ev_window: The window where dialogs will be closed.
+ *
+ * It looks for password, print and properties dialogs and closes them and
+ * frees them from memory. If there is any print job it does free it too.
+ */
 static void
 ev_window_close_dialogs (EvWindow *ev_window)
 {
@@ -5187,6 +5212,13 @@ ev_window_init (EvWindow *ev_window)
 	ev_window_setup_action_sensitivity (ev_window);
 }
 
+/**
+ * ev_window_new:
+ *
+ * Creates a #GtkWidget that represents the window.
+ *
+ * Returns: the #GtkWidget that represents the window.
+ */
 GtkWidget *
 ev_window_new (void)
 {
diff --git a/shell/main.c b/shell/main.c
index 3abe4cd..932e327 100644
--- a/shell/main.c
+++ b/shell/main.c
@@ -66,6 +66,24 @@ value_free (GValue *value)
 	g_free (value);
 }
 
+/**
+ * arguments_parse:
+ *
+ * Parses the arguments and creates a #GHashTable with this data.
+ *
+ *  key                 ->  value
+ *
+ *  dislay              ->  display at the default screen.
+ *  screen              ->  screen number.
+ *  page-label          ->  only if the page label argument has been passed,
+ *                          the page of the document to display.
+ *  mode                ->  only if the view mode is one of the availables,
+ *                          the view mode.
+ *  unlink-temp-file    ->  only if the view mode is preview mode and
+ *                          unlink-temp-file has been passed, unlink-temp-file.
+ *
+ * Returns: a pointer into #GHashTable with data from the arguments.
+ */
 static GHashTable *
 arguments_parse (void)
 {