GNOME Bugzilla – Bug 518427
documentation best pratices needed
Last modified: 2010-06-09 15:16:03 UTC
This is something I just realized while reading documentation for libsoup, and thought I'd dump it before I forget it again: The SUBSECTION Standard part is used differently between various projects because there is no general rule as to which symbols need to be documented and which don't. Some examples of differences between various projects: - Does an object structure (like GtkWidget or SoupSocket) need to be documented? - Should classes (like GtkWidgetClass or PangoRendererClass) and in particular their vfuncs be documented? - Should boxed types (like GDK_TYPE_RECTANGLE or G_TYPE_REGEX) be documented? You might have noticed that I've taken examples here where one contains documented symbols and the other doesn't. ;) At least the gtk-doc documentation should give best practices for which symbols should or should not be documented. Ideally gtk-doc would automatically remove symbols that should not be documented.
I am happy to include such in gtk-doc manual together with eventual changes in the tools. Now the question is who can come up with the guidelines. My opinion below: - object structures and class structure need docs if they have public members. If they are totally opaque its of questionable use to document them. One would basically document that e.g.: XyzThing: Opaque handle to a XzyThing instance. - vfuncs should imho be documented. That said it seems to be awkward to do so right now. One needs to document the member and ideally do a typedef for the functionpointer and document that too). - no idea about boxed types. never used them myself. Regarding removing symbols that don't needs docs - there are some bugs which are slighly releated: bug #324880: at least when you start documenting classes, this is annoying bug #166363: we should not require putting the standard gobject macros to any section at all
There is also some discussion here http://live.gnome.org/DocumentationProject/Planning/DeveloperDocs and one desktop-devel-list
Just recording the results of IRC discussion on that matter here. Dummy docs like "Opaque handle to a XzyThing instance." are not really useful and should be avoided. They also cause two index entries (one for the section and one for the object). This happens a lot in GStreamer - search for GstBus in devhelp. => GtkDoc needs to be smart enough to realise that object structs with no public methods are not undocumented. This avoids that people add dummy docs or manually hide the symbol in section.txt.
There's one thing that I think is important about this: The term "GtkWidget" needs to exist. I search for terms like these when I want to get an overview about something - I usually want it to take me to the top of the page about GtkWidget, which it doesn't do currently. There's also the point that GtkWidget gets linked in function prototypes when it's used as an argument, and that should continue working. So I guess not outputting documentation for a struct is only a good idea if a proper link for it exists in the docs. In most cases it'd be great if it's the corresponding section. Not sure what to do if a type has no section though.
Benjamin, in GObject the section docs have the GtkWidget xml-id. The object struct is GtkWidget-struct. Visually they both look the same. Having dummy entries could get you to the middle of the page.
commit 73cded364959ffe54a5bb91f7578fa8c249a0ef9 Author: Stefan Kost <ensonic@users.sf.net> Date: Wed Jun 9 18:10:17 2010 +0300 docs: document more what should be documented and what not Give better advice for GObject instance and class structs. I hope that okay now. Please reopen if there are concrete ideas.