GNOME Bugzilla – Bug 615860
introspection annotations result in ugly docs
Last modified: 2010-05-21 09:24:12 UTC
Adding gobject-introspection annotations to the gtk doc comments in a file results in really weird, not very useful stuff ending up in the generated documentation. These additions are strangely formatted, don't fit in with the sentences around them, are often redundant with other information that is already presented more readably ("or %NULL", "The caller must free the result."), and link to a strange glossary containing information that is not especially useful to people reading the docs. I would much rather have gtk-doc just completely strip out and ignore the annotations. As it is now, I am very likely just remove the annotations from my inline docs, and put them into a separate file which is only seen by g-ir-scanner and not gtk-doc.
I agree that the current presentations is not very nice. I disagree with banning it from the output unconditionaly. I have asked for opinions in the past, but got no feedback really. Having it in the docs is good, as it gives more information about the API. After all we have e.g. "const int i" in the docs as it is and don't expand it to "an integer i that value is not changed" :) Lets use this example: * @label: (allow-none): an optional string, ... 1) should we have a different syntax to omit the extra text from the docs * @label: [allow-none]: an optional string, ... 2) should we style the extra text differently (I see the addition as a 'icon' that gives extra information (there is the tooltip with explanation)). - we could colorize it, or in some way detach it more form the text 3) should we spell it out? I was not in favour of puuting the whole sentence there as the generated text would most likely not blend with the handwritten text. I don't like to have an option for adding/no adding it. And before agreeing of kicking it out, I'd like to try harder to see if we can make it nicer. It has been added to the doc-blobs for a reason.
(In reply to comment #1) > 1) should we have a different syntax to omit the extra text from the docs > * @label: [allow-none]: an optional string, ... That would require depending on a newer gobject-introspection too though... And in general, I think that if they're redundant, they're going to be redundant almost everywhere (and so it would be more useful to have a global --ignore-annotations flag). Maybe people are lax about things like "allow-none", but if you have an "out" parameter, there's no way the docs could fail to explain that and still be useful. > 2) should we style the extra text differently (I see the addition as a 'icon' > that gives extra information (there is the tooltip with explanation)). Yeah, I had that thought (icon+tooltip) too. Seems good in theory, but I can't imagine what the icons would look like that would be at all indicative... Maybe if the text was just some combination of smaller, dimmer, and farther away (eg, right-aligned)? I'd still like to get rid of the "glossary" section too though... > 3) should we spell it out? I was not in favour of puuting the whole sentence > there as the generated text would most likely not blend with the handwritten > text. Yeah, and the hand-written text can be more precise. "... or %NULL if you don't need to authenticate", etc.
That'd be unfortunate to remove the introspection annotations entirely from the docs; we should have some consistency among libraries as to their availability. I understand that in some cases they may be redundant. I personally prefer the introspection annotations over long strings like "Returns : a list of newly allocated GtkRecentInfo objects. Use gtk_recent_info_unref() on each item inside the list, and then free the list itself using g_list_free().". Yuck. But I think it'd be good if they were less in-your-face too, a smaller/dimmer font seems fine to me.
I pushed a commit to css style the annotation. Is that better or even enough? commit 506fa23e75550fe3aa9a022fcc37e94346ea4aae Author: Stefan Kost <ensonic@users.sf.net> Date: Wed Apr 21 22:29:16 2010 +0300 annotation: allow to style annotations with css Format the annotation using [] and style them using css. Hopefully fixes #615860.
Definitely better. I can probably be convinced to live with that. One problem remains: it adds an extra "." to certain lines that contain annotations. You can see this in gtk-doc/tests/annotations/docs/html/tester-GtkdocTester.html, in the Returns line for annotation_elementtype_returns. There are two "."s after "instances", even though there's only one in the source.
(In reply to comment #5) > Definitely better. I can probably be convinced to live with that. > > One problem remains: it adds an extra "." to certain lines that contain > annotations. You can see this in > gtk-doc/tests/annotations/docs/html/tester-GtkdocTester.html, in the Returns > line for annotation_elementtype_returns. There are two "."s after "instances", > even though there's only one in the source. Good catch. Fixed in git.
This has been released in 1.15