Re: Developer Documentation Plan

[Shaun McCance <shaunm gnome org>]

On Mon, 2010-03-01 at 14:31 +0000, Philip Withnall wrote:
> On Sun, 2010-02-28 at 21:05 -0600, Shaun McCance wrote:
> > Comments, suggestions, and flames are absolutely welcome.  Our
> > community is what makes us who we are.
> 
> I don't think I'll have time to work on any of this (sorry), but I had a
> few thoughts when reading through your plan:
> 
> How does the rearrangement/splitting up of reference pages tie in with
> Devhelp? The new hierarchy seems to be a lot more non-linear, with links
> going between tree branches, and I can foresee a little awkwardness
> trying to fit that into Devhelp's current navigation model (i.e.
> entirely tree-based). At the very least, Devhelp's tab support will have
> to be improved for this to be usable.

Good question.  My initial focus is on library.gnome.org.  It's not
that I don't think Devhelp is important.  It absolutely is.  But I
don't want to get bogged down on too many fronts.

So I'd like to get the changes on library with post-processing tools,
involving little to no changes to gtk-doc and other API documentation
tools.  Our experiences in doing this will help us better understand
how gtk-doc could be changed.  Since Devhelp works with generated HTML,
there's not much it can do without gtk-doc changes.

One thing I've been working on is splitting Yelp's transformation and
display engine into a separate library, libyelp.  We could use libyelp
in Devhelp to display the intros, howtos, and guides, so that Devhelp
becomes a very complete developer documentation viewer.

> I like the idea of hiding the documentation for getters/setters with the
> documentation for their respective properties, but what should be done
> about getters/setters which affect more than one property, or properties
> which are affected by more than one getter/setter? (e.g. An object has X
> and Y coordinate properties, but it makes sense for it to only have
> get_coordinate_pair() and set_coordinate_pair() functions.)

In this case, I would leave the function in the functions synopsis,
and not hide it behind the property.  A lot of functions are just
convenience APIs for dealing with multiple properties.  For example,
gtk_label_set_markup basically just sets "text" and "use-markup".

I'm not even sure how well we can match properties to accessors
programmatically.  I also did an HTML mockup of GtkLabel, with
more content than in my image mockup, and I didn't hide
gtk_label_get_line_wrap and gtk_label_get_line_wrap_mode behind
the "wrap" and "line-wrap" properties.  They don't match this
productions:

  label + "_get_" + tr(property, "-", "_")

So I don't know if we could even catch them.  There may just be
some quirks.  That's OK.  A 90% solution is better than nothing.

> How about extending gtk-doc's idea of API reference completeness so that
> only APIs which have full gobject-introspection (or similar) annotations
> are considered complete? I often find that, even if an API reference is
> complete in the traditional sense, I end up searching through the
> library's code to find out whether I should be freeing the return value
> of a function, and the appropriate free function to use when doing so.
> Mandating that all functions have the ownership of their return
> variables documented (e.g. using gobject-introspection annotations)
> would be of great help.

Yes, yes, yes!

> Moving on from that, it would be nice if the new API documentation style
> used gobject-introspection annotations better, and presented them as if
> they weren't just an afterthought (like here[1]).

> [1]:
> http://library.gnome.org/devel/gtk/unstable/GtkListStore.html#gtk-list-store-set-column-types

Yeah, definitely.  What we need to do is decide what information we
want to provide and mock up how we want to present it.  I did this
for the GtkLabel page, but we need to do this for other types of
page as well, like functions.  Then we figure out how to create
the output we want with the data we have.

> I like the plan as a whole, though. Just some food for thought. :-)

Thanks Philip.  This is very helpful.

--
Shaun