GNOME Bugzilla – Bug 744061
Skip standard g_iface, parent_instance and parent_class struct members
Last modified: 2015-09-22 14:41:43 UTC
It's boring to document them, better just ignore from gtk-doc. Suggested by desrt in bug #740814 comment #43.
Created attachment 296215 [details] [review] Ignore standard struct members
Code pushed as wip/xclaesse/fixes-for-glib
Review of attachment 296215 [details] [review]: +1 for the idea, but won't this cause warnings for existing docs about unused documentation? ::: gtkdoc-common.pl.in @@ +122,3 @@ + # Remove g_iface, parent_instance and parent_class if they are first member + $declaration =~ s/(\{)\s*(\w)+\s+(g_iface|parent_instance|parent_class)\s*;/$1/g; please also add 'parent' - I see that a lot in code. Would be good to also mention these naming requirements in the docs.
It does warn for unused symbol indeed, had to remove them in glib. Is there a way to skip them from unused as well? I was a bit scared that "parent" is too common. Where can this convention be documented?
I like this as well, and I particularly like that it hints people into using the stetic names for these fields.
I think the gobject docs should document the conventions. For gtk-doc help/manual/C/index.docbook is the documentation - search for "Struct comment block". We probably want to mention the special case for object, class and iface explicitly. The *_unused.txt is produced in gtkdoc-mkdb:OutputUnusedSymbols().
Created attachment 296298 [details] [review] Ignore standard struct members
Great, with this patch, g_iface/parent_instance/parent_class are silently ignored. And it's even documented trick now, even if I'm pretty sure nobody on earth will ever read that doc :p
Some people read the doc :) I wonder if you can run some find/grep magic do check for popular names here. I'll do that for gstreamer and se if I can also come up with a sed that drops the now not need doc-lines. Maybe we can add a TRACE line when dropping not needed docs, then one can build the docs with gtk-doc tracing enabled and grep the items that can be removed.
I did that on glib: for f in `git ls-files`; do sed -i '/ \* @g_iface/d' $f; done But didn't submit the resulting patch, because it's armless to keep them.
The following fix has been pushed: 1a24170 Ignore standard struct members
Created attachment 311875 [details] [review] Ignore standard struct members