Document obj.connect() and obj.disconnect()

api/mpi/docbookwriter.py

@@ -262,6 +262,7 @@ class Writer(object):
         mode = self.mode
 
         self.out.write("""\
+<!-- %(func_id)s -->
 <sect2 id="%(mode)s.%(func_id)s">
 <title id="%(mode)s.%(func_id)s.title">%(func_title)s</title>
 <programlisting>%(func_name)s(%(params_string)s)</programlisting>
@@ -345,6 +346,7 @@ class Writer(object):
             title += ' - ' + cls.summary.text
         dic = dict(class_id=cls.symbol_id(), title=title, mode=self.mode)
         self.out.write("""\
+<!-- %(class_id)s -->
 <sect1 id="%(mode)s.%(class_id)s">
 <title id="%(mode)s.%(class_id)s.title">%(title)s</title>
 """ % dic)
@@ -394,6 +396,7 @@ class Writer(object):
                    enum_id=enum.symbol_id())
 
         self.out.write("""\
+<!-- %(enum_id)s -->
 <sect2 id="%(mode)s.%(enum_id)s">
 <title id="%(mode)s.%(enum_id)s.title">%(title)s</title>
 """ % dic)
@@ -440,6 +443,7 @@ class Writer(object):
 
         if funcs:
             self.out.write("""\
+<!-- functions -->
 <sect1 id="%(mode)s.functions">
 <title>Functions</title>
 """ % dic)
@@ -450,6 +454,7 @@ class Writer(object):
             self.out.write('</sect1>\n')
 
         self.out.write("""\
+<!-- enums -->
 <sect1 id="%(mode)s.enums">
 <title>Enumerations</title>
 """ % dic)

doc/script-lua.tmpl.docbook

@@ -84,5 +84,65 @@ and <code>obj.method(args)</code>.
 </variablelist>
 
 </sect1>
+
+<!-- moo_edit_append_text -->
+<sect1 id="section-script-lua-signals">
+<title>Signals</title>
+
+<sect2 id="lua.g_signal_connect">
+<title id="lua.g_signal_connect.title">connect()</title>
+<programlisting>obj.connect(signal, callback)</programlisting>
+<para>Connect a signal handler.</para>
+<variablelist>
+  <?dbhtml list-presentation="table"?>
+  <?dbhtml term-separator=" : "?>
+  <varlistentry>
+    <term><parameter>signal</parameter></term>
+    <listitem><para>signal name</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><parameter>callback</parameter></term>
+    <listitem><para>a function to call when signal is emitted</para></listitem>
+  </varlistentry>
+</variablelist>
+<para><parameter>Returns:</parameter> id of connected signal handler. Use
+<function><link linkend="lua.g_signal_disconnect">disconnect()</link></function>
+to remove it.</para>
+<example>
+<programlisting>
+editor.connect("before-save", function(editor, doc, file)
+  if #doc.get_text() % 2 ~= 0 then
+    moo.error_dialog("Won't save",
+                     "Odd number of characters in a file " ..
+                     "is bad for your hard drive, I am not " ..
+                     "going to save this.",
+                     doc.get_window())
+    return moo.SAVE_RESPONSE_CANCEL
+  else
+    return moo.SAVE_RESPONSE_CONTINUE
+  end
+end)
+</programlisting>
+</example>
+</sect2>
+
+<sect2 id="lua.g_signal_disconnect">
+<title id="lua.g_signal_disconnect.title">disconnect()</title>
+<programlisting>obj.disconnect(handler_id)</programlisting>
+<para>Disconnect a signal handler.</para>
+<variablelist>
+  <?dbhtml list-presentation="table"?>
+  <?dbhtml term-separator=" : "?>
+  <varlistentry>
+    <term><parameter>handler_id</parameter></term>
+    <listitem><para>signal handler id returned from
+    <function><link linkend="lua.g_signal_connect">connect()</link></function>
+    </para></listitem>
+  </varlistentry>
+</variablelist>
+</sect2>
+
+</sect1>
+
 ###GENERATED###
 </chapter>