GNOME Bugzilla – Bug 674658
annotationparser: current code mix tags and description
Last modified: 2015-02-07 16:43:59 UTC
Created attachment 212635 [details] [review] annotationparser: do not mix tag and description A new line after a tag item in gtk doc comment is currently merged with the description item. This patch fixes this by adding PART_TAGS to the code that detect if a newline start a description section. This fixes farstream gstreamer-0.11 branch gir compilation error: ** (g-ir-compiler:19765): WARNING **: Unknown transfer-ownership value: 'This is the current preferences list for the local codecs. It is set by the user to specify the codec options and priorities. The user may change its value with fs_session_set_codec_preferences() at any time during a session. It is a #GList of #FsCodec. The user must free this codec list using fs_codec_list_destroy() when done. The payload type may be a valid dynamic PT (96-127), %FS_CODEC_ID_DISABLE or %FS_CODEC_ID_ANY. If the encoding name is "reserve-pt", then the payload type of the codec will be "reserved" and not be used by any dynamically assigned payload type.' for property 'codec-preferences' in type 'Farstream.Session ie : Transfer: full\n *\n*\n* This is the current preferences list for the local codecs. <...> are merged.
Review of attachment 212635 [details] [review]: This patch needs a regression test (add one to tests/scanner/regress.h).
Patch looks wrong to me as the only correct location for the comment block description is between the comment block parameters and comment block tags. So it doesn't make sense to restart parsing the comment block description once a tag has been seen? ie: /** * some-function: * param1: some parameter * param2: another parameter * * comment block description about * what some-function does * * Transfer: full * * * This is the current preferences list for the * local codecs. <...> */ Will correctly result in: identifier => 'some-function' parameters => [param1, param2] description => 'comment block description about\nwhat some-function does' tags => [Transfer], where the Transfer tag description is expected to be '\n\n\nThis is the current preferences list for the\nlocal codecs. <...>'
Thanks a lot for the review . The comment block is: /** * FsSession:codec-preferences: * * Type: GLib.List(FsCodec) * Transfer: full * * This is the current preferences list for the local codecs. It is * set by the user to specify the codec options and priorities. The user may * change its value with fs_session_set_codec_preferences() at any time * during a session. It is a #GList of #FsCodec. * The user must free this codec list using fs_codec_list_destroy() when done. * * The payload type may be a valid dynamic PT (96-127), %FS_CODEC_ID_DISABLE * or %FS_CODEC_ID_ANY. If the encoding name is "reserve-pt", then the * payload type of the codec will be "reserved" and not be used by any * dynamically assigned payload type. */ It turns out that with current gobject-introspection the above error disappeared. gdb was showing me empty line stripping the new lines between "Tranfer: full" and "This is the current preferences..." thus the gir was ending up with <property name="codec-preferences" transfer-ownership="full 'This is the current preferences list for the local codecs. It is set by the user to specify the codec options and priorities. The user ..." /> Nowadays the code renders correctly to: <property name="codec-preferences" transfer-ownership="full"> <doc xml:whitespace="preserve">This is the current preferences list for the local codecs. It is set by the user to specify the codec options and priorities. The user may change its value with fs_session_set_codec_preferences() at any time during a session. It is a #GList of #FsCodec. The user must free this codec list using fs_codec_list_destroy() when done. The payload type may be a valid dynamic PT (96-127), %FS_CODEC_ID_DISABLE or %FS_CODEC_ID_ANY. If the encoding name is "reserve-pt", then the payload type of the codec will be "reserved" and not be used by any dynamically assigned payload type.</doc> <type name="GLib.List"> <type name="Codec"/> </type> </property> So it turns out this was a bad fix for a real issue that looks like a locally too old gobject introspection. Thus marking as fixed.
reopening as I had forgotten to explcitely "rm" the Farstream-0.1 gir . Then with curren gi: <property name="codec-preferences" transfer-ownership="full This is the current preferences list for the local codecs. It is set by the user to specify the codec options and priorities. The user may change its value with fs_session_set_codec_preferences() at any time during a session. It is a #GList of #FsCodec. The user must free this codec list using fs_codec_list_destroy() when done. The payload type may be a valid dynamic PT (96-127), %FS_CODEC_ID_DISABLE or %FS_CODEC_ID_ANY. If the encoding name is "reserve-pt", then the payload type of the codec will be "reserved" and not be used by any dynamically assigned payload type."> <type name="GLib.List"> <type name="Codec"/> </type> </property>
Created attachment 213239 [details] [review] regression test for tag comment This test that a tag comment is not merged with its value.
Ah! So, that should be: /** * FsSession:codec-preferences: * * This is the current preferences list for the local codecs. It is * set by the user to specify the codec options and priorities. The user may * change its value with fs_session_set_codec_preferences() at any time * during a session. It is a #GList of #FsCodec. * The user must free this codec list using fs_codec_list_destroy() when done. * * The payload type may be a valid dynamic PT (96-127), %FS_CODEC_ID_DISABLE * or %FS_CODEC_ID_ANY. If the encoding name is "reserve-pt", then the * payload type of the codec will be "reserved" and not be used by any * dynamically assigned payload type. * * Type: GLib.List(FsCodec) * Transfer: full */ The parts that make up a GTK-Doc comment block have to be written in a specific order. The block shown in comment #3 has reversed the comment block description and the tags (Type: and Transfer:). The order (as parsed by gtkdoc-mkdb and the new annotationparser in g-i master) is as follows: 1) comment block starts with exactly 1 identifier on a single line 2) followed by 0 or more @parameters ! @parameter descriptions can not be written in multiple paragraphs because an empty line has special meaning at this location: 3) followed by exactly 1 empty line (this signals the end of the @parameters, even if there where none, and the beginning of the comment block description) 4) followed by an optional comment block description (can be written in multiple paragraphs) 5) followed by 0 or more Tags:
*** Bug 675915 has been marked as a duplicate of this bug. ***
(In reply to comment #6) > The order (as parsed by gtkdoc-mkdb and the new annotationparser > in g-i master) is as follows: The issue then is that from their perspective it's a regression, since g-i did accept the previous input. But are you guys willing to change your code to use the syntax that both g-i master and gtk-doc parse?
I filed bug 676133 to track the gtk-doc sides of this issue
*** Bug 679540 has been marked as a duplicate of this bug. ***
*** Bug 685494 has been marked as a duplicate of this bug. ***
This is now fixed in the master branch. We now accept g-i tags in the wrong location (but loudly complain about that) and no longer mangle the description. The "FsSession:codec-preferences:" comment block has been added to the tests to prevent future breakage here: https://git.gnome.org/browse/gobject-introspection/tree/tests/scanner/annotationparser/gi/tag.xml?id=9c5c43c01ef4e2f81c4bedb9da613fd5a1dccd82#n324
[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]