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 683361 - Generate link to free/unref function for return values and out arguments which transfer ownership
Generate link to free/unref function for return values and out arguments whic...
Status: RESOLVED OBSOLETE
Product: gtk-doc
Classification: Platform
Component: general
unspecified
Other Linux
: Normal enhancement
: ---
Assigned To: gtk-doc maintainers
gtk-doc maintainers
Depends on:
Blocks:
 
 
Reported: 2012-09-04 20:06 UTC by Evan Nemerson
Modified: 2018-05-22 13:06 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description Evan Nemerson 2012-09-04 20:06:07 UTC
It is currently common practice to add comments to out arguments and return values to "free with #whatever_free".  This works for C, but it is very confusing for people using languages with automatic memory management (Vala, Python, JS, etc.).  Now that those languages are beginning to rely on gtk-doc comments via GObject Introspection for documentation, it seems like a good idea to remove those bits from the comments and have gtk-doc generate similar information automatically so that languages for which such statements are irrelevant don't have to include them.
Comment 1 Stefan Sauer (gstreamer, gtkdoc dev) 2012-09-04 20:54:20 UTC
You mean that gtk-doc will add the "Free using g_free()" when generating the docbook files? This idea needs more work. Where do we specify free function? How will gtkdoc figure out the right free function.
Comment 2 Evan Nemerson 2012-11-04 23:23:11 UTC
Adding a few defaults for the types in glib/gobject would be a good start (GObject, GList, GSList, GHashTable, etc.).

For boxed types it wouldn't be hard to add a function to gtype to retrieve the symbol of the free function (I would be willing to write the patch), then use dladdr to get the symbol name.  If that doesn't work (e.g., dladdr not available or no symbol at that address) fall back on g_boxed_free.

Perhaps just (or additionally) a way to add an annotation (G-I style) about which free function to use.
Comment 3 Stefan Sauer (gstreamer, gtkdoc dev) 2012-11-06 09:37:59 UTC
Adding text is easy. The hard part is to figure case where it is already there. I am not really sure what exactly you'd like t get changed.
Comment 4 Evan Nemerson 2012-11-06 18:12:52 UTC
Eventually, I want to remove the existing bits from comments.  I don't think there is a feasible way to have gtkdoc do that automatically so it will have to be done manually.

The problem is that just removing the information isn't enough, since it makes the C documentation harder to read.  Therefore, I would like gtkdoc to automatically add some text referencing the correct free function in its output.  Once that is done you have references to the free function in the C documentation but tools to generate documentation for other languages (like valadoc and g-ir-doc-tool) can omit that information.
Comment 5 Yeti 2012-11-06 18:33:05 UTC
(In reply to comment #4)
> Eventually, I want to remove the existing bits from comments.  I don't think
> there is a feasible way to have gtkdoc do that automatically so it will have to
> be done manually.

‘It will have to be done’ says little about who will fix all third-party software documentation...

And more importantly, how will projects make the documentation usable when built with both older or newer gtk-doc?  What sad state will be their documentation in during the transition?

Finally, imagine GString, GArray and similar data structures.  Annotation needs a function to free it completely.  Fine.  But a useful human-written documentation says something along the lines of ‘you have to free the return value using my_foo_free(), however, you can also use my_foo_other_free() which frees only the container, retaining the data’.

What you suggest must be *voluntary*.  I would prefer simple explicit markup expanded by gtk-doc to the boilerplate free-function description.  Probably an option always-generate-the-free-func-description could be added for projects that are OK with that and do not have any useful human-written descriptions anyway.
Comment 6 Evan Nemerson 2013-02-15 06:32:06 UTC
(In reply to comment #5)
> (In reply to comment #4)
> > Eventually, I want to remove the existing bits from comments.  I don't think
> > there is a feasible way to have gtkdoc do that automatically so it will have to
> > be done manually.
> 
> ‘It will have to be done’ says little about who will fix all third-party
> software documentation...

I honestly don't know how to respond to that.  It sounds like you're trying to say that this change shouldn't be made because at some point people should update their software.  By that logic, we shouldn't ever add new APIs, and we definitely shouldn't deprecate old ones.

> And more importantly, how will projects make the documentation usable when
> built with both older or newer gtk-doc?  What sad state will be their
> documentation in during the transition?

Worst case scenario is you have some duplicate information.  Just like how right now you sometimes see annotations like "[out]" or "[closure]" alongside of explanations like "location to store xyz" or "data to pass to callback function".  I actually think this would make things easier--I often find myself just looking at the annotations instead of reading the description because it's less effort once you understand what those annotations do.

> Finally, imagine GString, GArray and similar data structures.  Annotation needs
> a function to free it completely.  Fine.  But a useful human-written
> documentation says something along the lines of ‘you have to free the return
> value using my_foo_free(), however, you can also use my_foo_other_free() which
> frees only the container, retaining the data’.

You can (and should) still keep explanations like that.  I'm not suggesting we eliminate your ability to put whatever you like in comments, only that we formalize a *very* common use case so that documentation for languages other than C become slightly less horrible.

> What you suggest must be *voluntary*.  I would prefer simple explicit markup
> expanded by gtk-doc to the boilerplate free-function description.  Probably an
> option always-generate-the-free-func-description could be added for projects
> that are OK with that and do not have any useful human-written descriptions
> anyway.

Why?  Is a little "[free-function g_free]" (or whatever) note really such a terrible thing?  If you really want to opt-out you can always tweak a stylesheet, but I don't see a problem with treating it like any existing g-i annotation.
Comment 7 Stefan Sauer (gstreamer, gtkdoc dev) 2014-02-18 08:32:46 UTC
If we introduce an explicit annotation (in the gi style), we can do it. As in this case it won't add any text by default and people can migrate their docs to use the annotation if they prefer.

What I am still worried about is that the annotation would expand to a text blob. Right now annoations are rendered as 'tags' at the end of the doc-target they refer to and one can get more details when hovering with the mouse over them.
Technically we can mark the annotations in the sources one-by-one wheter the should be rendered in the classic way (as now) or should be expanded in place.
Comment 8 Evan Nemerson 2014-02-18 08:49:07 UTC
(In reply to comment #7)
> What I am still worried about is that the annotation would expand to a text
> blob. Right now annoations are rendered as 'tags' at the end of the doc-target
> they refer to and one can get more details when hovering with the mouse over
> them.

With my C programmer hat on, I don't mind rendering them as tags.  I actually prefer that since it's easier to tell with just a glance what the function does, but that relies on understanding the annotations so it may not be very beginner-friendly.

> Technically we can mark the annotations in the sources one-by-one wheter the
> should be rendered in the classic way (as now) or should be expanded in place.

That sounds painful.  I think a way to set the default per-project would be much nicer.

FWIW, if this is going to require an explicit annotation I think it would be much nicer to have the annotation on the type instead of having to specify it for every function with a return value or out param which transfers ownership.  Of course, you most likely also require a way to annotate how to free containers with of that type (like g_strfreev and gnome_keyring_acl_free).
Comment 9 Stefan Sauer (gstreamer, gtkdoc dev) 2014-02-18 09:38:29 UTC
Indeed, having the annotation on the type would be nice. Unfortunately that make it harder to implement has gtkdoc would need to load this information also for dependent libraries to apply the metadata to the current docs.

I would be nice to have a gir reader in gtk-doc ...
Comment 10 Evan Nemerson 2014-05-27 00:15:49 UTC
How about using the unref-func annotation?  If we change the description from "The specified function is used to unref a struct, must be a GTypeInstance." to something like "Use the specified function to unref." it works okay from gtk-doc's point of view, and it's only a few lines of code in G-I to just ignore it instead of warning about unref-func being an unexpected annotation.

Assuming that works for you, I'll talk to the G-I people and make sure they're okay with the idea, too.
Comment 11 Stefan Sauer (gstreamer, gtkdoc dev) 2018-05-06 18:05:13 UTC
gtk-doc was done for libraries written in C. If we want to 'transcode' docs so that they are useful for bindings, this probably needs more though.

I think the suggestions in this ticket are too focused on addressing one issue. I believe a better approach would be to collect a list of samples from documentation that is language specific and then think of ways to handle this. E.g. per language overrides, tags etc.

I would prefer to have a general concept for this. Are you still interested doing this?
Comment 12 GNOME Infrastructure Team 2018-05-22 13:06:52 UTC
-- GitLab Migration Automatic Message --

This bug has been migrated to GNOME's GitLab instance and has been closed from further activity.

You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/gtk-doc/issues/23.