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 > [email protected] > http://mail.gnome.org/mailman/listinfo/desktop-devel-list _______________________________________________ desktop-devel-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/desktop-devel-list
