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 659851 - "Rename to:" annotation needs to be converted to the proper style or gtk-doc needs to be patched to handle it
"Rename to:" annotation needs to be converted to the proper style or gtk-doc ...
Status: RESOLVED FIXED
Product: gobject-introspection
Classification: Platform
Component: general
unspecified
Other Linux
: Normal normal
: ---
Assigned To: gobject-introspection Maintainer(s)
gobject-introspection Maintainer(s)
Depends on:
Blocks:
 
 
Reported: 2011-09-22 18:15 UTC by Dan Winship
Modified: 2015-02-07 16:54 UTC
See Also:
GNOME target: ---
GNOME version: ---


Description Dan Winship 2011-09-22 18:15:31 UTC 
If I have:

/**
 * soup_buffer_new_take:
 * @data: (array length=length) (transfer full): data
 * @length: length of @data
 *
 * Creates a new #SoupBuffer containing @length bytes from @data.
 *
 * This function is exactly equivalent to soup_buffer_new() with
 * %SOUP_MEMORY_TAKE as first argument; it exists mainly for
 * convenience and simplifying language bindings.
 *
 * Return value: the new #SoupBuffer.
 *
 * Since: 2.32
 * Rename to: soup_buffer_new
 **/

gtk-doc complains:

../../libsoup/soup-message-body.c:126: warning: multi-line since docs found

but if I swap the order of the "Since" and "Rename to" tags, it's fine
Comment 1 Dan Winship 2011-09-22 18:16:00 UTC 
(adding a blank line doesn't help either)
Comment 2 Stefan Sauer (gstreamer, gtkdoc dev) 2011-09-22 18:59:00 UTC 
Rename to: is not a gtk-doc tag and thus gets interpreted as part of the since: tag. If you want to add your own 'tags' have them at the end of the body part.
Comment 3 Dan Winship 2011-09-22 20:38:51 UTC 
note that "Rename to" is a valid gobject-introspection annotation...
Comment 4 Stefan Sauer (gstreamer, gtkdoc dev) 2011-09-23 08:44:41 UTC 
Well, they should probably have talked to me then regarding the format. So far the syntax was different. This annotation would be written as

/**
 * soup_buffer_new_take: (rename-to soup_buffer_new)
 * @data: (array length=length) (transfer full): data
 * ...
 */

I'll discuss it will the gobject-introspection people
Comment 5 Stefan Sauer (gstreamer, gtkdoc dev) 2011-09-23 13:39:05 UTC 
The GI folks want to keep that syntax and will make a patch for gtk-doc to handle it.
Comment 6 Stefan Sauer (gstreamer, gtkdoc dev) 2013-05-30 19:22:52 UTC 
I have not got a patch so far. Reassigning to gi.
Comment 7 Dieter Verfaillie 2013-10-10 19:53:28 UTC 
as of yesterday g-ir-scanner understands the syntax from comment #4 :

/**
 * soup_buffer_new_take: (rename-to soup_buffer_new)
 * @data: (array length=length) (transfer full): data
 * ...
 */

and complains with deprecation warnings for the old syntax:

* Rename to: soup_buffer_new

Other than deprecation warnings, the old syntax is obviously
still parsed by g-ir-scanner for backwards compatibility.
Comment 8 André Klapper 2015-02-07 16:54:20 UTC 
[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]