RDP, GTK+-1.4

[Owen Taylor <otaylor redhat com>]

Now that GTK+-1.4 is getting closer, I've been thinking some recently
about documentation. 

There are various issues that arise here:

 - At some point we will want to move the focus of the GTK+ documentation
   from GTK+-1.2 to GTK+-1.4 (while maintaining the GTK+-1.2
   docs)

 - We may (or may not) want to switch to using inline documentation.

 - We probably want to bundle the documentation with the packages instead
   having

 - GObject (especially in its current state where it doesn't handle signals)
   poses various problems for the runtime-query parts of gtk-doc.

The components of the GTK+-1.4 platform will be:

 GLib - complete API docs in glib-reference
 Pango - (pretty much) complete API docs inline
 gdk-pixbuf - complete API docs inline
 GTK+ - incomplete docs in gtk-reference

Note that generating the docs for GLib, Pango and gdk-pixbuf all
depends on gtk-doc, which depends on GTK+. So, this is a conceptually
a nasty dependency loop.

In practice it isn't too bad, since the dependency on gtk-doc on
GTK+ is weak - it doesn't actually include anything linked against
GTK+, and also we will want to ship the documentation built since we
don't want to depend on docbook/jade.

Transitioning to GTK+ 1.4
=========================

I think the right thing to copy glib-reference and gtk-reference into
the GLib and GTK+ trees respectively and then update the versions in
the GTK+ trees to 1.4 while leaving the 

Inline docs
===========

To repeat advantages and disadvantages:

 Advantages:

  - Easier to remember to add and update. 
  - Docs are there when reading the code.

 Disadvantages:

  - Can lead to paying attention to the function docs while neglecting
    structure/enumeration docs and section overview docs which are
    not inline.

  - Some (timj) consider the inline docs excessive noise in the code,
    especially for things like:

     gtk_label_set_text:
     @label: a #GtkLabel
     @text: the new text for the label
   
     Sets the text in the label.

I'm a bit in favor of going to inline docs.

I'd appreciate any thoughts, opinions, whatever, on these issues.

                                        Owen