GNOME Bugzilla – Bug 673752
Switch to gtk-doc syntax
Last modified: 2012-04-24 19:25:38 UTC
I started writing this patch back in November, when we were going to start building documentation for the St/Shell libraries. Now that gobject-introspection doesn't like the new syntax, I dusted it off and finished it.
Created attachment 211597 [details] [review] Switch to gtk-doc syntax
Review of attachment 211597 [details] [review]: In general, I believe non-namespaced functions should not have /**. (This is to ensure that Meta.gir doesn't see private stuff) ::: src/core/bell.c @@ +143,3 @@ + * bell_flash_fullscreen: + * @display: The display the event came in on + * @xkb:_ev The bell event Empty line here, or everything is placed under @xkb_ev. @@ +271,3 @@ /** + * bell_visual_notify: + * @display The display the bell event came in on Missing colon here. ::: src/core/main.c @@ +36,3 @@ * Many window managers are like Marshmallow Froot Loops; Mutter + * is like Frosted Flakes: it's still plain old corn, but dusted + * with some sugar. What do you have against Cheerios? :) ::: src/core/prefs.c @@ +172,2 @@ /** + * handler: I don't think this is right. Shouldn't it be /** * Struct: * @field1: * @field2: */ ?
(In reply to comment #2) > Review of attachment 211597 [details] [review]: > > In general, I believe non-namespaced functions should not have /**. > (This is to ensure that Meta.gir doesn't see private stuff) We may have been trying that at one point, but nowadays it's preferable to just omit private headers from the list of files passed to the scanner. That way you don't have to remember to add a '*' when making a private function public.
The scanner also ignores static functions.
Created attachment 211888 [details] [review] Switch to gtk-doc syntax I'm not sure how multi-line descriptions really work for the struct fields. This is my best guess.
*** Bug 674386 has been marked as a duplicate of this bug. ***
Review of attachment 211888 [details] [review]: Thanks a ton for diving into this and writing a patch! ::: src/core/main.c @@ +36,3 @@ * Many window managers are like Marshmallow Froot Loops; Mutter + * is like Frosted Flakes: it's still plain old corn, but dusted + * with some sugar. Haha...bonus points for sneaking this change into the middle of a big patch. ::: src/core/prefs.c @@ +184,3 @@ + * This may be %NULL. If it is, see "target", below. + * + * @target: (allow-none): Where to write the incoming string. Parameters should be first, then a documentation body. So something like: @handler: (allow-none): Callback for processing parameter @target: (allow-none): Where to write the incoming string. Many of the string preferences aren't stored...
Created attachment 212728 [details] [review] Switch to gtk-doc syntax Yeah, unfortunately newlines like that aren't allowed in gtk-doc syntax. This is suboptimal, but it builds.
Review of attachment 212728 [details] [review]: Looks good, thanks!
Attachment 212728 [details] pushed as 044d589 - Switch to gtk-doc syntax