GNOME Bugzilla – Bug 403485
Move docs from tmpl/* to the source files
Last modified: 2010-03-06 15:17:08 UTC
Having the docs in two places is a bit of a pain. For quite a while now (cf. bug 165963) gtk-doc has been able to get everything it gets from template files from the actual source. So we can use that and be happier. If this is seen as a good idea, we can do this one file at a time ;-) Here comes a patch for a simple one, just for HEAD (doing it for the current stable branch too seems like too much work IMO)
Created attachment 81741 [details] [review] Do it for GtkAccelLabel
Created attachment 81743 [details] [review] Do it for gtkImage
Please don't add periods after the variable descriptions, I spend a long time getting rid of them... I am not entirely convinced of adding everything to the sources yet. I'd like to hear other peoples opinion on that first.
Moving docs to sources is all win and no lose. The templates beat us in cairo every release time. Since the function docs are already in source files, remains the section headers. If you really don't like to see them in the source file, they can be all moved into a new source file.
I don't think adding a new source file is a good idea. I can probably live with pushing the docs into the individual source files, but I'd like to hear the opinions of some other people on this. I know that e.g. TimJ has protested when I tried to move gobject (function) docs inline.
In GStreamer I did the move of the docs from tmpl -> src and this helps enoumously to keep docs up-to-date and improve them over time. We have the section docs in the c-file (to avoid a whole rebuild if one touches the docs and to avoid bloating the h-files).
when writing the clutter API reference we decided to go with the inlined documentation (inside the C sources) instead of relying on templates. this helped a lot and reduced the number of files under VCS. having the long description of a class inside the object itself always helps when adding new features, and reduces the commits distance (just a single commit, vs. one for the code and one for the template). it also keeps the documentation near the implementation, making it easier to go back and forth. without having two editor windows open. it could even motivate developers to add more comments and officially document the invariants of a class. so, definitely +1 for moving documentation away from templates and into the source.
Pango and cairo want to do that too. Last I checked we needed gtk-doc from CVS for it to fully work. Don't remember why (Damon wrote on cairo-list about it).
Dear gtk developers, please acceppt the attached patches. That was quite some work. To let you know. I try to write a tool (in gtk-doc) that tries to backport docs semiautomatic.
I am also in favor of having documentation in the sources, the API documentation should in my opinion be as close as possible to the actual source code. Officially marking the patches as needs-work, since at least the trailing dots should be removed.
Mariano, if you want to help: http://live.gnome.org/GTK%2B/TaskAPIDocMigration
Comment on attachment 81743 [details] [review] Do it for gtkImage Obsolete, GtkImage documentation is already ported
Created attachment 152889 [details] [review] GtkAccelLabel Here a new patch against current master
Review of attachment 152889 [details] [review]: Other than the coding style in the example, patch looks good. Please fix that up while you commit it. ::: gtk/gtkaccellabel.c @@ +75,3 @@ + * GtkAccelGroup *accel_group; + * + * // Create a GtkAccelGroup and add it to the window. Please keep the coding style in examples the same as in GTK+ code: no // comments.
Comment on attachment 152889 [details] [review] GtkAccelLabel I've fixed the patch with your comments commit 2adef27d7b16612e0a4f2f0cffee1a726a660fcd
Close this bug as all the patches are committed and the tracker of this work is bug #599599