Re: Developer Documentation Plan

[Stefan Kost <ensonic hora-obscura de>]

Am 01.03.2010 16:31, schrieb Philip Withnall:
> On Sun, 2010-02-28 at 21:05 -0600, Shaun McCance wrote:
>> Hi folks,
>>
>> For the last week, I've been putting together a comprehensive
>> plan to overhaul and update our developer documentation.  My
>> plan is on live.gnome.org:
>>
>> http://live.gnome.org/DocumentationProject/Planning/DeveloperDocs
> 
> *snip*
> 
>> 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.
> 
> 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.)

One problem here is the style that many libraries have choosen. You have gobject
properties. Those should be documented. I see explicit setters and getter as
"c-bindings", as the other bindings won't use them anyway. Personally I simply
don't add setters/getters to my lib and use g_object_set|get.

I would not mind hiding them in gtk-doc, if I could easily identify them.

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

If anyone has good suggestions, please shoot. I can output the annotation data
in anyway.

Stefan

> 
> I like the plan as a whole, though. Just some food for thought. :-)
> 
> Regards,
> Philip
> 
> [1]:
> http://library.gnome.org/devel/gtk/unstable/GtkListStore.html#gtk-list-store-set-column-types
> 
> 
> 
> _______________________________________________
> desktop-devel-list mailing list
> desktop-devel-list gnome org
> http://mail.gnome.org/mailman/listinfo/desktop-devel-list