GNOME Bugzilla – Bug 593282
Append "_struct" prefix to every struct name
Last modified: 2018-05-22 13:02:43 UTC
Created attachment 141844 [details] [review] Append "_struct" prefix to every struct name Actually the "_struct" prefix is added only if the struct is a GObject based: this prevents to have the same section and struct id for non-gobject struct. A typical case I often meet is a section describing a GBoxed type with its methods: I have to force a different section name to avoid id conflicts.
Created attachment 141854 [details] [review] A more generic approach that does name mangling on all types New option (--type-name-mangling) to automatically append suffixes to typedef, struct, enum and union. If not specifically enabled gtkdoc-mkdb behaves as before, retaining backward compatibility.
Hmm, now I understand the problem, but I don't like the options so much. For new projects the options is fine (but they will most probably miss it). If one adds this later one, we would need a way to check if there are links that needs to be fixed. Also starting to use this later one would need all other docs to be re-fixxreffed, right?
There are several options new projects can use (and benefit from) but old, stable, important and historical-crap-encumbered projects can't... I'm afraid documenting the options (especially in the sample Makefile) is the best we can do. Re-fixrefing would be a big problem for e.g. GLib as you cannot make references that work both with and without --type-name-mangling. But it's is less a problem for projects closer to the top of the food chain, e.g. I can do that in Gwyddion libs without causing much grief. The way to check that the links are correct is already present: fixxref prints warnings about dangling links. So I'd enable this optionally, as suggested.
Enabling the option by default in the sample makefile will likely improve its adoption by new projects. On older project, especially the non GObject-based ones, enabling --type-name-mangling is more problematic: all the eventual links to fields need to be rewritten. I don't think this is a big issue, anyway the maintainer can choose when (and if) switch on this option. I agree this is another hack to be piled up on top of gtk-doc, though.
For the record the problem at hand is that when introspecting boxed types, enums, flags etc. (that is adding there _get_types function to the .types file), one gets warnings (e.g as in gtk-doc's gobject test suite): ../xml/types.xml:42: element refsect2: validity error : ID GtkdocEnum already defined <refsect2 id="GtkdocEnum" role="enum"> ^ This comes from the fact that in the generated xml we have: <anchor id="GtkdocEnum"/> <refsect2 id="GtkdocEnum" role="enum"> For gobjects we disambiguate it in gtkdoc-mkdb::OutputStruct() via CheckIsObject(); and append a "_struct" to the id of <refsect2> What I will try no is to do the same the other artifacts, but not using a switch. That is we only add the postfix when we would add an anchors too. This way no links break (they would just be pointing to a slighly earlier point in the file). Does this sound reasonable?
Created attachment 185931 [details] [review] WIP patch for enums This fixes the issues for the tests.
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/gtk-doc/issues/9.