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.) 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]). 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
Attachment:
signature.asc
Description: This is a digitally signed message part