Structs and enums automation

[Owen Taylor <otaylor redhat com>]

After doing a bit more work with gtk-doc recently,
I've come to the conclusion that 80% of the effort
is dealing with structs and enumerations:

 - You have to cut-and-paste the <informatltable> template
   from the style-guide file.
 - You have to look up the memebers in the header files
 - There is an unwieldy amount of taggage for each
   member.

Plus, we can't easily change the SGML markup we use
for these table later.
I think these tables need to be automated in the
same way that functions are. I thought I'd run
my ideas for doing this before this group before
digging into the Perl.

So:

=======
<!-- ##### ENUM GdkJoinStyle ##### -->
<para>
Determines how the joins between segments of a polygon are drawn.

<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>

<row>
<entry>GDK_JOIN_MITER</entry>
<entry>the sides of each line are extended to meet at an angle.</entry>
</row>

<row>
<entry>GDK_JOIN_ROUND</entry>
<entry>the sides of the two lines are joined by a circular arc.</entry>
</row>

<row>
<entry>GDK_JOIN_BEVEL</entry>
<entry>the sides of the two lines are joined by a straight line which
       makes an equal angle with each line.</entry>
</row>

</tbody></tgroup></informaltable>
</para>


Becomes:

========
<!-- ##### ENUM GdkJoinStyle ##### -->
<para>
Determines how the joins between segments of a polygon are drawn.
</para>

@GDK_JOIN_MITER: the sides of each line are extended to meet at an angle.
@GDK_JOIN_ROUND: the sides of the two lines are joined by a circular arc.
@GDK_JOIN_BEVEL: the sides of the two lines are joined by a straight line 
                 which makes an equal angle with each line.
========

and:

========
<!-- ##### STRUCT GdkDeviceKey ##### -->
<para>
The #GdkDeviceKey structure contains information
about the mapping of one device macro button onto
a normal X key event. It has the following fields:

<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>

<row>
<entry>guint <structfield>keyval</structfield></entry>
<entry>the keyval to generate when the macro button is pressed.
       If this is 0, no keypress will be generated.</entry>
</row>

<row>
<entry>GdkModifierType <structfield>modifiers</structfield></entry>
<entry>the modifiers set for the generated key event.</entry>
</row>

</tbody></tgroup></informaltable>
</para>
========

becomes:

========
<!-- ##### STRUCT GdkDeviceKey ##### -->
<para>
The #GdkDeviceKey structure contains information
about the mapping of one device macro button onto
a normal X key event. It has the following fields:
</para>

@keyval: the keyval to generate when the macro button is pressed.
          If this is 0, no keypress will be generated.
@modifiers: the modifiers set for the generated key event.
========

To ease the transition, we can make the Perl scripts omit
the automated table when none of the members of a struct
or enumeration are given; in that way, currently documented
structs and enumerations will still appear OK.

I suspect that we should also have a way of documenting
structs and enumerations inline, for those using the
inline-docs mode of gtk-doc, but that can be implemented
later.

A suggestion for a format might be something like:

=========
struct _GdkDeviceKey
{
  /*< docs="The #GdkDeviceKey structure contains information
            about the mapping of one device macro button onto
            a normal X key event. It has the following fields: >*/

  guint keyval;
  /*< docs="the keyval to generate when the macro button is pressed.
            If this is 0, no keypress will be generated." >*/
  GdkModifierType modifiers;
  /*< docs="the modifiers set for the generated key event." >*/
};
=========

or

=========
struct _GdkDeviceKey
{
  /** The #GdkDeviceKey structure contains information
   *  about the mapping of one device macro button onto
   *  a normal X key event. It has the following fields:
   */

  guint keyval;
  /** the keyval to generate when the macro button is pressed.
   *  If this is 0, no keypress will be generated.
   */
  GdkModifierType modifiers;
  /** the modifiers set for the generated key event.
   */
};
=========

Depending on whether you want to be GTK+-ish or gnome-doc-ish.

Regards,
                                        Owen