Move some docs inline

svn path=/trunk/; revision=18447

5 files changed, 42 insertions, 13 deletions

diff --git a/ChangeLog b/ChangeLog
index 7e4377dbe2..8595201de2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2007-07-11  Matthias Clasen  <mclasen@redhat.com>
+
+	* gtk/gtkplug.c:
+	* gtk/gtksocket.c: Move docs inline, and add some missing
+	docs.  
+
 2007-07-11  Kristian Rietveld  <kris@imendio.com>
 
 	* gtk/gtktreeview.c (gtk_tree_view_*_to_*_coords): x should be
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index a6c00e11e5..1dbcf924d5 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,5 +1,10 @@
 2007-07-11  Matthias Clasen  <mclasen@redhat.com>
 
+	* gtk/tmpl/gtkplug.sgml:
+	* gtk/tmpl/gtksocket.sgml: Move docs inline
+
+2007-07-11  Matthias Clasen  <mclasen@redhat.com>
+
 	* gtk/gtk-sections.txt: Updates
 
 2007-07-11  Matthias Clasen  <mclasen@redhat.com>
diff --git a/docs/reference/gtk/tmpl/gtksocket.sgml b/docs/reference/gtk/tmpl/gtksocket.sgml
index 1f32d69564..f20b6e0f3d 100644
--- a/docs/reference/gtk/tmpl/gtksocket.sgml
+++ b/docs/reference/gtk/tmpl/gtksocket.sgml
@@ -59,7 +59,8 @@ When GTK+ is notified that the embedded window has been
 destroyed, then it will destroy the socket as well. You
 should always, therefore, be prepared for your sockets
 to be destroyed at any time when the main event loop
-is running.
+is running. To prevent this from happening, you can
+connect to the #GtkSocket::plug-removed signal.
 </para>
 
 <para>
@@ -112,25 +113,17 @@ never be set by an application.)
 
 <!-- ##### SIGNAL GtkSocket::plug-added ##### -->
 <para>
-This signal is emitted when a client is successfully
-added to the socket.
+
 </para>
 
-@socket: the object which received the signal.
-<!-- # Unused Parameters # -->
-@socket_: the object which received the signal.
+@socket_: 
 
 <!-- ##### SIGNAL GtkSocket::plug-removed ##### -->
 <para>
-This signal is emitted when a client is removed from the socket. The
-default action is to destroy the #GtkSocket widget, so if you want to
-reuse it you must add a signal handler that returns %TRUE.
+
 </para>
 
-@socket: the object which received the signal.
-@Returns: 
-<!-- # Unused Parameters # -->
-@socket_: the object which received the signal.
+@socket_: 
 
 <!-- ##### FUNCTION gtk_socket_new ##### -->
 <para>
diff --git a/gtk/gtkplug.c b/gtk/gtkplug.c
index f9ca4eff8a..8266804a32 100644
--- a/gtk/gtkplug.c
+++ b/gtk/gtkplug.c
@@ -148,6 +148,13 @@ gtk_plug_class_init (GtkPlugClass *class)
 							 FALSE,
 							 GTK_PARAM_READABLE));
 
+  /**
+   * GtkPlug::embedded:
+   * @plug: the object on which the signal was emitted
+   *
+   * Gets emitted when the plug becomes embedded in a socket
+   * and when the embedding ends.
+   */ 
   plug_signals[EMBEDDED] =
     g_signal_new (I_("embedded"),
 		  G_OBJECT_CLASS_TYPE (class),
diff --git a/gtk/gtksocket.c b/gtk/gtksocket.c
index 8f54f58804..af66729067 100644
--- a/gtk/gtksocket.c
+++ b/gtk/gtksocket.c
@@ -144,6 +144,13 @@ gtk_socket_class_init (GtkSocketClass *class)
   container_class->remove = gtk_socket_remove;
   container_class->forall = gtk_socket_forall;
 
+  /**
+   * GtkSocket::plug-added:
+   * @socket_: the object which received the signal
+   *
+   * This signal is emitted when a client is successfully
+   * added to the socket. 
+   */
   socket_signals[PLUG_ADDED] =
     g_signal_new (I_("plug_added"),
 		  G_OBJECT_CLASS_TYPE (class),
@@ -152,6 +159,17 @@ gtk_socket_class_init (GtkSocketClass *class)
 		  NULL, NULL,
 		  _gtk_marshal_VOID__VOID,
 		  G_TYPE_NONE, 0);
+
+  /**
+   * GtkSocket::plug-removed:
+   * @socket_: the object which received the signal
+   *
+   * This signal is emitted when a client is removed from the socket. 
+   * The default action is to destroy the #GtkSocket widget, so if you 
+   * want to reuse it you must add a signal handler that returns %TRUE. 
+   *
+   * Return value: %TRUE to stop other handlers from being invoked.
+   */
   socket_signals[PLUG_REMOVED] =
     g_signal_new (I_("plug_removed"),
 		  G_OBJECT_CLASS_TYPE (class),