GNOME.org
 

[anjuta] libanjuta: Added some more documentation

commit 9ff55c436a96edfdc9a58a50116b1c8b10ffff7d
Author: Johannes Schmid <jhs gnome org>
Date:   Thu May 6 10:48:23 2010 +0200

    libanjuta: Added some more documentation

 libanjuta/anjuta-async-command.c        |   16 ++++++++++++++-
 libanjuta/anjuta-async-command.h        |    6 ++--
 libanjuta/anjuta-c-module.c             |    9 ++++++++
 libanjuta/anjuta-command-queue.c        |   18 ++++++++++++++++
 libanjuta/anjuta-command.c              |    4 ++-
 libanjuta/anjuta-convert.h              |    6 +++++
 libanjuta/anjuta-plugin-description.h   |    8 +++++++
 libanjuta/anjuta-ui.h                   |   27 ++++++++++++++++++++++--
 libanjuta/anjuta-utils.h                |   33 ++++++++++++++++++++++++++++++-
 manuals/reference/libanjuta/Makefile.am |    2 +-
 10 files changed, 119 insertions(+), 10 deletions(-)
---
diff --git a/libanjuta/anjuta-async-command.c b/libanjuta/anjuta-async-command.c
index 1b46fb2..b0e438d 100644
--- a/libanjuta/anjuta-async-command.c
+++ b/libanjuta/anjuta-async-command.c
@@ -178,9 +178,16 @@ anjuta_async_command_class_init (AnjutaAsyncCommandClass *klass)
 	parent_class->notify_progress = notify_progress;
 }
 
+/**
+ * anjuta_async_command_set_error_message:
+ * @command: AnjutaAsyncCommand object
+ * @error_message: The error message that should be used
+ *
+ * Set the error message this async command resulted in
+ */
 void
 anjuta_async_command_set_error_message (AnjutaCommand *command, 
-										gchar *error_message)
+										const gchar *error_message)
 {
 	anjuta_async_command_lock (ANJUTA_ASYNC_COMMAND (command));
 	ANJUTA_COMMAND_GET_CLASS (command)->set_error_message (command, 
@@ -188,6 +195,13 @@ anjuta_async_command_set_error_message (AnjutaCommand *command,
 	anjuta_async_command_unlock (ANJUTA_ASYNC_COMMAND (command));
 }
 
+/**
+ * anjuta_async_command_get_error_message:
+ * @command: AnjutaAsyncCommand object
+ *
+ * Returns: The error message the async command resulted in. The caller
+ * should free the string
+ */
 gchar *
 anjuta_async_command_get_error_message (AnjutaCommand *command)
 {
diff --git a/libanjuta/anjuta-async-command.h b/libanjuta/anjuta-async-command.h
index 729c5f5..62daaf2 100644
--- a/libanjuta/anjuta-async-command.h
+++ b/libanjuta/anjuta-async-command.h
@@ -36,8 +36,8 @@ G_BEGIN_DECLS
 #define ANJUTA_TYPE_ASYNC_COMMAND             (anjuta_async_command_get_type ())
 #define ANJUTA_ASYNC_COMMAND(obj)             (G_TYPE_CHECK_INSTANCE_CAST ((obj), ANJUTA_TYPE_ASYNC_COMMAND, AnjutaAsyncCommand))
 #define ANJUTA_ASYNC_COMMAND_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST ((klass), ANJUTA_TYPE_ASYNC_COMMAND, AnjutaAsyncCommandClass))
-#define IS_ANJUTA_ASYNC_COMMAND(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), ANJUTA_TYPE_ASYNC_COMMAND))
-#define IS_ANJUTA_ASYNC_COMMAND_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE ((klass), ANJUTA_TYPE_ASYNC_COMMAND))
+#define ANJUTA_IS_ASYNC_COMMAND(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), ANJUTA_TYPE_ASYNC_COMMAND))
+#define ANJUTA_IS_ASYNC_COMMAND_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE ((klass), ANJUTA_TYPE_ASYNC_COMMAND))
 #define ANJUTA_ASYNC_COMMAND_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS ((obj), ANJUTA_TYPE_ASYNC_COMMAND, AnjutaAsyncCommandClass))
 
 typedef struct _AnjutaAsyncCommandClass AnjutaAsyncCommandClass;
@@ -59,7 +59,7 @@ struct _AnjutaAsyncCommand
 GType anjuta_async_command_get_type (void) G_GNUC_CONST;
 
 void anjuta_async_command_set_error_message (AnjutaCommand *command, 
-											 gchar *error_message);
+											 const gchar *error_message);
 gchar *anjuta_async_command_get_error_message (AnjutaCommand *command);
 
 void anjuta_async_command_lock (AnjutaAsyncCommand *self);
diff --git a/libanjuta/anjuta-c-module.c b/libanjuta/anjuta-c-module.c
index 79e82ff..31e85a7 100644
--- a/libanjuta/anjuta-c-module.c
+++ b/libanjuta/anjuta-c-module.c
@@ -188,6 +188,15 @@ anjuta_c_module_init (AnjutaCModule *module)
 /* Public functions
  *---------------------------------------------------------------------------*/
 
+/**
+ * anjuta_c_module_get_last_error:
+ * @module: AnjutaCModule object
+ * @err: return location for a GError
+ *
+ * Receives the error that occured when the module was loaded
+ *
+ * Returns: TRUE if there was an Error, FALSE otherwise
+ */
 gboolean
 anjuta_c_module_get_last_error (AnjutaCModule *module, GError** err)
 {
diff --git a/libanjuta/anjuta-command-queue.c b/libanjuta/anjuta-command-queue.c
index d7da3fb..f6a46bc 100644
--- a/libanjuta/anjuta-command-queue.c
+++ b/libanjuta/anjuta-command-queue.c
@@ -19,6 +19,15 @@
 
 #include "anjuta-command-queue.h"
 
+/**
+ * SECTION: anjuta-command-queue
+ * @short_description: #AnjutaCommandQueue is used to queue commands
+ * @include: libanjuta/anjuta-async-command.h
+ *
+ * #AnjutaCommandQueue always starts the next command in the queue when
+ * the previous command finishes. That also works for asyncronous commands
+ */
+
 struct _AnjutaCommandQueuePriv
 {
 	GQueue *queue;
@@ -93,6 +102,15 @@ anjuta_command_queue_new (void)
 	return g_object_new (ANJUTA_TYPE_COMMAND_QUEUE, NULL);
 }
 
+/**
+ * anjuta_command_queue_push:
+ * @self: AnjutaCommandQueue object
+ * @command: The command to add
+ *
+ * Adds a command to the Queue and starts it if there are no other commands
+ * waiting
+ */
+
 void
 anjuta_command_queue_push (AnjutaCommandQueue *self, AnjutaCommand *command)
 {
diff --git a/libanjuta/anjuta-command.c b/libanjuta/anjuta-command.c
index 8ac354a..d2713c3 100644
--- a/libanjuta/anjuta-command.c
+++ b/libanjuta/anjuta-command.c
@@ -206,7 +206,8 @@ anjuta_command_notify_data_arrived (AnjutaCommand *self)
 
 /**
  * anjuta_command_notify_complete:
- * @self: Command object.
+ * @self: Command object
+ * @return_code: The returned code that is passed to the notify callback
  * 
  * Used by base classes derived from #AnjutaCommand to emit the 
  * ::command-finished signal. This method should not be used by client code or  
@@ -221,6 +222,7 @@ anjuta_command_notify_complete (AnjutaCommand *self, guint return_code)
 /**
  * anjuta_command_notify_progress:
  * @self: Command object.
+ * @progress: The of the command that is passed to the notify callback
  * 
  * Emits the ::progress signal. Can be used by both base classes and 
  * commands as needed. 
diff --git a/libanjuta/anjuta-convert.h b/libanjuta/anjuta-convert.h
index 8cb2172..59e2827 100644
--- a/libanjuta/anjuta-convert.h
+++ b/libanjuta/anjuta-convert.h
@@ -33,6 +33,12 @@
 #include <glib.h>
 #include "anjuta-encodings.h"
 
+/**
+ * AnjutaConvertError:
+ * @ANJUTA_CONVERT_ERROR_AUTO_DETECTION_FAILED: The charset couldn't be autodetected
+ *
+ * Possibly errors that can occur during charset conversion
+ */
 typedef enum 
 {
 	ANJUTA_CONVERT_ERROR_AUTO_DETECTION_FAILED = 1100
diff --git a/libanjuta/anjuta-plugin-description.h b/libanjuta/anjuta-plugin-description.h
index ae2838a..8710faf 100644
--- a/libanjuta/anjuta-plugin-description.h
+++ b/libanjuta/anjuta-plugin-description.h
@@ -39,6 +39,14 @@ typedef void (*AnjutaPluginDescriptionLineFunc) (AnjutaPluginDescription *df,
 												 const gchar *value,
 												 gpointer   data);
 
+/**
+ * AnjutaPluginDescriptionParseError:
+ * @ANJUTA_PLUGIN_DESCRIPTION_PARSE_ERROR_INVALID_SYNTAX: Syntax of plugin file is invalid
+ * @ANJUTA_PLUGIN_DESCRIPTION_PARSE_ERROR_INVALID_ESCAPES: Invalid escape sequence
+ * @ANJUTA_PLUGIN_DESCRIPTION_PARSE_ERROR_INVALID_CHARS: Invalid characters
+ *
+ * Possible errors when parsing a plugin file
+ */
 typedef enum
 {
   ANJUTA_PLUGIN_DESCRIPTION_PARSE_ERROR_INVALID_SYNTAX,
diff --git a/libanjuta/anjuta-ui.h b/libanjuta/anjuta-ui.h
index 196eadb..bee3e97 100644
--- a/libanjuta/anjuta-ui.h
+++ b/libanjuta/anjuta-ui.h
@@ -137,7 +137,12 @@ void anjuta_ui_save_accels (const gchar *filename);
 
 void anjuta_ui_unload_accels (AnjutaUI *ui);
 
-/* Convenience macros to register stock icons */
+/**
+ * BEGIN_REGISTER_ICON:
+ * @plugin: The anjuta plugin to register the icons for
+ *
+ * Convenience macros to register stock icons 
+ */
 #define BEGIN_REGISTER_ICON(plugin) \
 { \
 	AnjutaUI *ui = anjuta_shell_get_ui ((plugin)->shell, NULL); \
@@ -145,7 +150,12 @@ void anjuta_ui_unload_accels (AnjutaUI *ui);
 	GtkIconSet *icon_set; \
 	GtkIconSource *	icon_source = gtk_icon_source_new ();
 
-/* Register icon with size 16 and size 24, icon should be the 
+/**
+ * REGISTER_ICON_FULL:
+ * @icon: name of the icon (without size and extension)
+ * @stock_id: stock-id that should be assigned to the icon
+ *
+ * Register icon with size 16 and size 24, icon should be the 
  * filename (without path) striped of the size (16,24) and the *.png
  * (e.g anjuta-icon-24.png => anjuta-icon)
  */
@@ -162,7 +172,12 @@ void anjuta_ui_unload_accels (AnjutaUI *ui);
 	gtk_icon_set_add_source (icon_set, icon_source); \
 	gtk_icon_factory_add (icon_factory, stock_id, icon_set);
 
-/* Register icon for all sizes (will be scaled) 
+/**
+ * REGISTER_ICON:
+ * @icon: name of the icon (without size and extension)
+ * @stock_id: stock-id that should be assigned to the icon
+ *
+ * Register icon for all sizes (will be scaled) 
  * icon should be the full filename without path (e.g anjuta-icon.png)
  */
 
@@ -177,6 +192,12 @@ void anjuta_ui_unload_accels (AnjutaUI *ui);
 	} \
 	}
 
+
+/** 
+ * END_REGISTER_ICON:
+ *
+ * Ends a BEGIN_REGISTER_ICON sequence
+ */
 #define END_REGISTER_ICON \
 	gtk_icon_source_free (icon_source); \
 }
diff --git a/libanjuta/anjuta-utils.h b/libanjuta/anjuta-utils.h
index c5ef85e..baf65a0 100644
--- a/libanjuta/anjuta-utils.h
+++ b/libanjuta/anjuta-utils.h
@@ -149,6 +149,15 @@ GSList *anjuta_utils_drop_get_files (GtkSelectionData *selection_data);
 
 /* Temporarily copied here */
 
+/**
+ * ANJUTA_TYPE_BEGIN:
+ * @class_name: Name of the object
+ * @prefix: Prefix used for object methods
+ * @parent_type: The parent type of the object
+ *
+ * Create a new GObject for Anjuta. You can use ANJUTA_TYPE_ADD_INTERFACE
+ * to add interfaces to it and should close it using ANJUTA_TYPE_END
+ */
 #define ANJUTA_TYPE_BEGIN(class_name, prefix, parent_type) \
 GType                                                     \
 prefix##_get_type (void)                                  \
@@ -172,11 +181,24 @@ prefix##_get_type (void)                                  \
         type = g_type_register_static (parent_type,       \
                                        #class_name,       \
                                        &type_info, 0);
+
+/**
+ * ANJUTA_TYPE_END
+ *
+ * Ends a declaration that began with ANJUTA_TYPE_BEGIN
+ */
 #define ANJUTA_TYPE_END                                   \
      }                                                    \
   return type;                                            \
 }
 
+/**
+ * ANJUTA_TYPE_ADD_INTERFACE:
+ * @prefix: Prefix for the interface methods
+ * @interface_type: Type of the interface to implement
+ *
+ * Adds an interface to a declaration started with ANJUTA_TYPE_BEGIN
+ */
 #define ANJUTA_TYPE_ADD_INTERFACE(prefix,interface_type)  \
     {                                                     \
         GInterfaceInfo iface_info = {                     \
@@ -189,10 +211,19 @@ prefix##_get_type (void)                                  \
                                      &iface_info);        \
     }
 
+/**
+ * ANJUTA_TYPE_BOILERPLATE:
+ * @class_name: Name of the object
+ * @prefix: Prefix for the class methods
+ * @parent_type: Parent type for object
+ *
+ * Simpliefied version of ANJUTA_TYPE_BEGIN that just creates an Object
+ * without interfaces and doesn't need ANJUTA_TYPE_END
+ */
 #define ANJUTA_TYPE_BOILERPLATE(class_name, prefix, parent_type) \
 ANJUTA_TYPE_BEGIN(class_name, prefix, parent_type);              \
 ANJUTA_TYPE_END
 
 G_END_DECLS
 
-#endif
+#endif
\ No newline at end of file
diff --git a/manuals/reference/libanjuta/Makefile.am b/manuals/reference/libanjuta/Makefile.am
index 356784b..ab97d5c 100644
--- a/manuals/reference/libanjuta/Makefile.am
+++ b/manuals/reference/libanjuta/Makefile.am
@@ -42,7 +42,7 @@ CFILE_GLOB=$(top_srcdir)/libanjuta/*.c $(top_srcdir)/libanjuta/interfaces/ianjut
 
 # Header files to ignore when scanning.
 # e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
-IGNORE_HFILES=
+IGNORE_HFILES=anjuta-enum-types.h anjuta-marshal.h
 
 # Images to copy into HTML directory.
 # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]