Re: Thoughts on mm-common and gmmproc

[Krzesimir Nowak <qdlacz gmail com>]

On Thu, 2010-01-07 at 09:43 +0100, Murray Cumming wrote:
> We hope to use the new .gir files, which should actually be correct and
> widely shared:
> http://live.gnome.org/GObjectIntrospection
> 
> However, I hope any gmmproc rewrite does the .defs/.gir switch as a
> separate task. 
> 

.gir files would be almost perfect replacement for current .defs. Pity
it only contains only partial docs:

from Gio-2.0.gir:

<constructor name="new" c:identifier="g_socket_new" throws="1">
  <return-value transfer-ownership="full">
    <type name="Socket" c:type="GSocket*"/>
  </return-value>
  <parameters>
    <parameter name="family" transfer-ownership="none">
      <type name="SocketFamily" c:type="GSocketFamily"/>
    </parameter>
    <parameter name="type" transfer-ownership="none">
      <type name="SocketType" c:type="GSocketType"/>
    </parameter>
    <parameter name="protocol" transfer-ownership="none">
      <type name="SocketProtocol" c:type="GSocketProtocol"/>
    </parameter>
  </parameters>
</constructor>

no docs for <parameter> or <return-value>.

<bitfield name="AppInfoCreateFlags"
          doc="Flags used when creating a #GAppInfo."
          glib:type-name="GAppInfoCreateFlags"
          glib:get-type="g_app_info_create_flags_get_type"
          c:type="GAppInfoCreateFlags">
  <member name="none"
          value="0"
          c:identifier="G_APP_INFO_CREATE_NONE"
          glib:nick="none"/>
  <member name="needs_terminal"
          value="1"
          c:identifier="G_APP_INFO_CREATE_NEEDS_TERMINAL"
          glib:nick="needs-terminal"/>
  <member name="supports_uris"
          value="2"
          c:identifier="G_APP_INFO_CREATE_SUPPORTS_URIS"
          glib:nick="supports-uris"/>
</bitfield>

no docs for each <member> of flags/enums.

from GLib-2.0.gir

<record name="Array" c:type="GArray">
  <field name="data" writable="1">
    <type name="utf8" c:type="gchar*"/>
  </field>
  <field name="len" writable="1">
    <type name="uint" c:type="guint"/>
  </field>
</record>

no docs for each <field>.

It looks like for comments like this:
/**
 * my_whatever:
 * @one: a first something
 * @two: a second something
 *
 * This is whatever.
 */
.gir files have only "This is whatever". I am wondering if doc attribute
could be added for every <member> or <parameter> or <return-value>
to .gir format by gobject-introspection maintainers. This way we could
avoid using/writing docs extractor.

Krzesimir