GNOME Bugzilla – Bug 673385
Fix malformed GTK-Doc comment blocks
Last modified: 2012-04-05 21:28:28 UTC
The gobject-instrospection annotation parser work from bug #672254 requires some fixes to malformed GTK-Doc comment blocks in order for make check to pass. This because the improved parser emits warnings when something doesn't look right, which are treated as errors by the test suite. Patches following shortly.
Created attachment 211177 [details] [review] Fix malformed GTK-Doc comment blocks: add missing colons. Found these thanks to improved gobject-introspection GTK-Doc comment block/annotation parser from: https://bugzilla.gnome.org/show_bug.cgi?id=672254
Created attachment 211178 [details] [review] Fix malformed GTK-Doc comment blocks: invalid parameters and tags. Found these thanks to improved gobject-introspection GTK-Doc comment block/annotation parser from: https://bugzilla.gnome.org/show_bug.cgi?id=672254
Created attachment 211179 [details] [review] Fix malformed GTK-Doc comment blocks: unmark non GTK-Doc comment block. Found these thanks to improved gobject-introspection GTK-Doc comment block/annotation parser from: https://bugzilla.gnome.org/show_bug.cgi?id=672254
Created attachment 211180 [details] [review] Fix malformed GTK-Doc comment blocks: mutliline annotations are invalid. Found these thanks to improved gobject-introspection GTK-Doc comment block/annotation parser from: https://bugzilla.gnome.org/show_bug.cgi?id=672254
Created attachment 211181 [details] [review] Fix malformed GTK-Doc comment blocks: correct struct name. Found these thanks to improved gobject-introspection GTK-Doc comment block/annotation parser from: https://bugzilla.gnome.org/show_bug.cgi?id=672254
Created attachment 211182 [details] [review] Fix malformed GTK-Doc comment blocks: don't confuse GTK-Doc parsers. Found these thanks to improved gobject-introspection GTK-Doc comment block/annotation parser from: https://bugzilla.gnome.org/show_bug.cgi?id=672254
Created attachment 211183 [details] [review] Fix malformed GTK-Doc comment blocks: remove repeated comment blocks. Found these thanks to improved gobject-introspection GTK-Doc comment block/annotation parser from: https://bugzilla.gnome.org/show_bug.cgi?id=672254
All these patches looks good to me, as long as the output of gtk-doc doesn't change significantly.
Review of attachment 211182 [details] [review]: The "Notatag\:" trick doesn't work, the backslash is rendered visible in GTK-Doc html output. Looks like baskslash only works for '<', '>', '()', '@', '%', or '#' characters :(
Review of attachment 211183 [details] [review]: I'm not sure I've removed the correct duplicates any more? Which one is considered current, the comment block showing up in current documentation on developer.gnome.org or the comment block that doesn't? Think I'll need help on this...
Review of attachment 211177 [details] [review]: this looks fine, thanks
Review of attachment 211178 [details] [review]: Looks good, otherwise ::: glib/gasyncqueue.c @@ +177,3 @@ * Increases the reference count of the asynchronous @queue by 1. * + * Deprecated: Since 2.8, reference counting is done atomically I think this should even be Deprecated:2.8: Since 2.8 ... ? ::: gobject/gtype.c @@ +4059,3 @@ * macro. * + * Returns: #TRUE if @instance is valid, #FALSE otherwise. %TRUE and %FALSE, while we are at it
Review of attachment 211179 [details] [review]: sure
Review of attachment 211180 [details] [review]: sure
Review of attachment 211181 [details] [review]: ok
Created attachment 211241 [details] [review] In reply to comment #12 and comment #13 > Review of attachment 211178 [details] [review]: > > Looks good, otherwise > > ::: glib/gasyncqueue.c > @@ +177,3 @@ > * Increases the reference count of the asynchronous @queue by 1. > * > + * Deprecated: Since 2.8, reference counting is done atomically > > I think this should even be > > Deprecated:2.8: Since 2.8 ... > > ? Fixed. Grepping the code shows the following to be used: "Deprecated: X.Y: Describe why here." > ::: gobject/gtype.c > @@ +4059,3 @@ > * macro. > * > + * Returns: #TRUE if @instance is valid, #FALSE otherwise. > > %TRUE and %FALSE, while we are at it Fixed. Thank you for the review!
Created attachment 211242 [details] [review] Fix malformed GTK-Doc comment blocks: don't confuse GTK-Doc parsers. In reply to comment #9 > Review of attachment 211182 [details] [review]: > > The "Notatag\:" trick doesn't work, the backslash is > rendered visible in GTK-Doc html output. Looks like > baskslash only works for '<', '>', '()', '@', '%', > or '#' characters :( Fixed as using ':', '(' and ')' to escape ':', '(' and ')' works fine for both GTK-Doc and g-i :)
Created attachment 211243 [details] [review] Fix malformed GTK-Doc comment blocks: remove repeated comment blocks. In reply to comment #10 > Review of attachment 211183 [details] [review]: > > I'm not sure I've removed the correct duplicates any more? > Which one is considered current, the comment block showing > up in current documentation on developer.gnome.org or the > comment block that doesn't? > > Think I'll need help on this... Diffed the original and patched GTK-Doc html output and it looks good to me. Some text changed a bit, but it is really hard to tell what block has the best description. Please review carefully.
Review of attachment 211241 [details] [review]: Looks fine now
Review of attachment 211242 [details] [review]: sure
Review of attachment 211243 [details] [review]: ok
I pushed these for Dieter today.
A big thank you to everybody involved!