gedit r6734 - branches/message_system/gedit

[jessevdk svn gnome org]

Author: jessevdk
Date: Sat Dec 27 19:08:38 2008
New Revision: 6734
URL: http://svn.gnome.org/viewvc/gedit?rev=6734&view=rev

Log:
Added section documentation for GeditMessage and GeditMessageType


Modified:
   branches/message_system/gedit/gedit-message-type.c
   branches/message_system/gedit/gedit-message.c

Modified: branches/message_system/gedit/gedit-message-type.c
==============================================================================
--- branches/message_system/gedit/gedit-message-type.c	(original)
+++ branches/message_system/gedit/gedit-message-type.c	Sat Dec 27 19:08:38 2008
@@ -1,5 +1,40 @@
 #include "gedit-message-type.h"
 
+/**
+ * SECTION:gedit-message-type
+ * @short_description: message type description
+ * @include: gedit/gedit-message-type.h
+ *
+ * A message type is a prototype description for a #GeditMessage used to
+ * transmit messages on a #GeditMessageBus. The message type describes
+ * the Object Path, Method and Arguments of the message.
+ *
+ * A message type can contain any number of required and optional arguments.
+ * To instantiate a #GeditMessage from a #GeditMessageType, use 
+ * gedit_message_type_instantiate().
+ *
+ * Registering a new message type on a #GeditMessageBus with
+ * gedit_message_bus_register() internally creates a new #GeditMessageType. When
+ * then using gedit_message_bus_send(), an actual instantiation of the 
+ * registered type is internally created and send over the bus.
+ *
+ * <example>
+ * <programlisting>
+ * // Defining a new message type
+ * GeditMessageType *message_type = gedit_message_type_new ("/plugins/example",
+ *                                                          "method",
+ *                                                          0,
+ *                                                          "arg1", G_TYPE_STRING,
+ *                                                          NULL);
+ *
+ * // Instantiating an actual message from the type
+ * GeditMessage *message = gedit_message_type_instantiate (message_type,
+ *                                                         "arg1", "Hello World",
+ *                                                         NULL);
+ * </programlisting>
+ * </example>
+ *
+ */
 typedef struct
 {
 	GType type;

Modified: branches/message_system/gedit/gedit-message.c
==============================================================================
--- branches/message_system/gedit/gedit-message.c	(original)
+++ branches/message_system/gedit/gedit-message.c	Sat Dec 27 19:08:38 2008
@@ -4,6 +4,21 @@
 #include <string.h>
 #include <gobject/gvaluecollector.h>
 
+/**
+ * SECTION:gedit-message
+ * @short_description: message bus message object
+ * @include: gedit/gedit-message.h
+ *
+ * Communication on a #GeditMessageBus is done through messages. Messages are
+ * sent over the bus and received by connecting callbacks on the message bus.
+ * A #GeditMessage is an instantiation of a #GeditMessageType, containing
+ * values for the arguments as specified in the message type.
+ *
+ * A message can be seen as a method call, or signal emission depending on
+ * who is the sender and who is the receiver. There is no explicit distinction
+ * between methods and signals.
+ *
+ */
 #define GEDIT_MESSAGE_GET_PRIVATE(object)(G_TYPE_INSTANCE_GET_PRIVATE((object), GEDIT_TYPE_MESSAGE, GeditMessagePrivate))
 
 enum {