Re: Developer Documentation Plan

[Stefan Kost <ensonic hora-obscura de>]

Am 01.03.2010 19:19, schrieb Shaun McCance:
> 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.

It might be easier to do some changes closer to the source. I can check the
feasibiloty from gtk-doc side.

> 
> 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.

Any I was thinking about (optionally) generating omf files in gtk-doc and
allowing to install the plain docbook documents as well (so that they show up in
yelp).

> 
>> 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.

In the long-run we could use a new section for accessor methods in gtk-docs
<lib>-section.txt file.

Stefan