After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 403485 - Move docs from tmpl/* to the source files
Move docs from tmpl/* to the source files
Product: gtk+
Classification: Platform
Component: Documentation
Other All
: Normal normal
: ---
Assigned To: gtk-bugs
Depends on:
Blocks: 599599
Reported: 2007-02-02 07:54 UTC by Mariano Suárez-Alvarez
Modified: 2010-03-06 15:17 UTC
See Also:
GNOME target: ---
GNOME version: ---

Do it for GtkAccelLabel (10.79 KB, patch)
2007-02-02 07:55 UTC, Mariano Suárez-Alvarez
needs-work Details | Review
Do it for gtkImage (25.58 KB, patch)
2007-02-02 09:03 UTC, Mariano Suárez-Alvarez
none Details | Review
GtkAccelLabel (10.52 KB, patch)
2010-02-02 22:48 UTC, Javier Jardón (IRC: jjardon)
committed Details | Review

Description Mariano Suárez-Alvarez 2007-02-02 07:54:34 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)
Comment 1 Mariano Suárez-Alvarez 2007-02-02 07:55:24 UTC
Created attachment 81741 [details] [review]
Do it for GtkAccelLabel
Comment 2 Mariano Suárez-Alvarez 2007-02-02 09:03:09 UTC
Created attachment 81743 [details] [review]
Do it for gtkImage
Comment 3 Matthias Clasen 2007-02-16 02:28:54 UTC
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.
Comment 4 Behdad Esfahbod 2007-02-16 04:29:14 UTC
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.
Comment 5 Matthias Clasen 2007-02-16 04:41:14 UTC
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.
Comment 6 Stefan Sauer (gstreamer, gtkdoc dev) 2007-06-05 08:01:59 UTC
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).
Comment 7 Emmanuele Bassi (:ebassi) 2007-06-05 09:13:25 UTC
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.
Comment 8 Behdad Esfahbod 2007-06-05 11:13:21 UTC
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).
Comment 9 Stefan Sauer (gstreamer, gtkdoc dev) 2007-08-24 17:57:35 UTC
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.
Comment 10 Johan (not receiving bugmail) Dahlin 2008-03-03 01:34:34 UTC
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.
Comment 11 Stefan Sauer (gstreamer, gtkdoc dev) 2008-07-10 03:33:47 UTC
Mariano, if you want to help:
Comment 12 Javier Jardón (IRC: jjardon) 2010-01-14 10:38:00 UTC
Comment on attachment 81743 [details] [review]
Do it for gtkImage

Obsolete, GtkImage documentation is already ported
Comment 13 Javier Jardón (IRC: jjardon) 2010-02-02 22:48:34 UTC
Created attachment 152889 [details] [review]

Here a new patch against current master
Comment 14 Matthias Clasen 2010-02-09 00:35:45 UTC
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 15 Javier Jardón (IRC: jjardon) 2010-02-09 03:15:37 UTC
Comment on attachment 152889 [details] [review]

I've fixed the patch with your comments

commit 2adef27d7b16612e0a4f2f0cffee1a726a660fcd
Comment 16 Javier Jardón (IRC: jjardon) 2010-03-06 15:17:08 UTC
Close this bug as all the patches are committed and the tracker of this work is bug #599599