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 673385 - Fix malformed GTK-Doc comment blocks
Fix malformed GTK-Doc comment blocks
Status: RESOLVED FIXED
Product: glib
Classification: Platform
Component: general
unspecified
Other All
: Normal normal
: ---
Assigned To: gtkdev
gtkdev
Depends on:
Blocks: 672254
 
 
Reported: 2012-04-02 19:11 UTC by Dieter Verfaillie
Modified: 2012-04-05 21:28 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
Fix malformed GTK-Doc comment blocks: add missing colons. (5.30 KB, patch)
2012-04-02 19:14 UTC, Dieter Verfaillie
committed Details | Review
Fix malformed GTK-Doc comment blocks: invalid parameters and tags. (2.82 KB, patch)
2012-04-02 19:14 UTC, Dieter Verfaillie
reviewed Details | Review
Fix malformed GTK-Doc comment blocks: unmark non GTK-Doc comment block. (887 bytes, patch)
2012-04-02 19:14 UTC, Dieter Verfaillie
committed Details | Review
Fix malformed GTK-Doc comment blocks: mutliline annotations are invalid. (1.05 KB, patch)
2012-04-02 19:14 UTC, Dieter Verfaillie
committed Details | Review
Fix malformed GTK-Doc comment blocks: correct struct name. (957 bytes, patch)
2012-04-02 19:14 UTC, Dieter Verfaillie
committed Details | Review
Fix malformed GTK-Doc comment blocks: don't confuse GTK-Doc parsers. (3.03 KB, patch)
2012-04-02 19:14 UTC, Dieter Verfaillie
needs-work Details | Review
Fix malformed GTK-Doc comment blocks: remove repeated comment blocks. (4.43 KB, patch)
2012-04-02 19:14 UTC, Dieter Verfaillie
needs-work Details | Review
In reply to comment #12 and comment #13 (2.82 KB, patch)
2012-04-03 18:29 UTC, Dieter Verfaillie
committed Details | Review
Fix malformed GTK-Doc comment blocks: don't confuse GTK-Doc parsers. (3.10 KB, patch)
2012-04-03 18:34 UTC, Dieter Verfaillie
committed Details | Review
Fix malformed GTK-Doc comment blocks: remove repeated comment blocks. (6.10 KB, patch)
2012-04-03 18:37 UTC, Dieter Verfaillie
committed Details | Review

Description Dieter Verfaillie 2012-04-02 19:11:58 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.
Comment 1 Dieter Verfaillie 2012-04-02 19:14:09 UTC
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
Comment 2 Dieter Verfaillie 2012-04-02 19:14:13 UTC
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
Comment 3 Dieter Verfaillie 2012-04-02 19:14:15 UTC
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
Comment 4 Dieter Verfaillie 2012-04-02 19:14:18 UTC
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
Comment 5 Dieter Verfaillie 2012-04-02 19:14:21 UTC
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
Comment 6 Dieter Verfaillie 2012-04-02 19:14:24 UTC
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
Comment 7 Dieter Verfaillie 2012-04-02 19:14:28 UTC
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
Comment 8 Johan (not receiving bugmail) Dahlin 2012-04-02 19:17:02 UTC
All these patches looks good to me, as long as the output of gtk-doc doesn't change significantly.
Comment 9 Dieter Verfaillie 2012-04-02 21:20:40 UTC
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 :(
Comment 10 Dieter Verfaillie 2012-04-02 21:22:00 UTC
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...
Comment 11 Matthias Clasen 2012-04-03 14:49:54 UTC
Review of attachment 211177 [details] [review]:

this looks fine, thanks
Comment 12 Matthias Clasen 2012-04-03 15:32:24 UTC
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
Comment 13 Matthias Clasen 2012-04-03 15:32:37 UTC
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
Comment 14 Matthias Clasen 2012-04-03 15:52:37 UTC
Review of attachment 211179 [details] [review]:

sure
Comment 15 Matthias Clasen 2012-04-03 16:12:24 UTC
Review of attachment 211180 [details] [review]:

sure
Comment 16 Matthias Clasen 2012-04-03 16:13:04 UTC
Review of attachment 211181 [details] [review]:

ok
Comment 17 Dieter Verfaillie 2012-04-03 18:29:38 UTC
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!
Comment 18 Dieter Verfaillie 2012-04-03 18:34:30 UTC
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 '&colon;', '&lpar;' and '&rpar;' to escape
':', '(' and ')' works fine for both GTK-Doc and g-i :)
Comment 19 Dieter Verfaillie 2012-04-03 18:37:21 UTC
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.
Comment 20 Matthias Clasen 2012-04-04 21:50:56 UTC
Review of attachment 211241 [details] [review]:

Looks fine now
Comment 21 Matthias Clasen 2012-04-04 21:52:34 UTC
Review of attachment 211242 [details] [review]:

sure
Comment 22 Matthias Clasen 2012-04-04 21:54:39 UTC
Review of attachment 211243 [details] [review]:

ok
Comment 23 Johan (not receiving bugmail) Dahlin 2012-04-05 14:45:45 UTC
I pushed these for Dieter today.
Comment 24 Dieter Verfaillie 2012-04-05 21:28:28 UTC
A big thank you to everybody involved!