[Bug 35117] Make gtk-doc nicer

[bugzilla-daemon at freedesktop.org]

https://bugs.freedesktop.org/show_bug.cgi?id=35117

Will Thompson <will.thompson at collabora.co.uk> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
  Status Whiteboard|                            |review-

--- Comment #1 from Will Thompson <will.thompson at collabora.co.uk> 2011-03-08 10:39:36 PST ---
+ * @WOCKY_NODE_START: Start of a node (less-than sign)

I think the parenthetical statement confuses more than it adds.

+/**
+ * WockyNodeIter:
+ * @pending: the list of children to still iterate over
+ * @name: name of the node to iterate over
+ * @ns: #GQuark of the namespace of the node to iterate over
+ *
+ * Iterate over a node's children. This struct should not be accessed
+ * directly -- see wocky_node_iter_init() for more details.
+ */

Just annotate the whole body as /*< private >*/.

> node: add a workaround for gtk-doc's parser being broken
> I'll file a bug, like, way soon.

Actually do that plz, and add the URL to the comment.

+ * @override_type: %TRUE whether this error should override the error
+ *   in @specializes, or %FALSE

This comment is wrong: this field signifies whether the following field, @type,
should be used, or whether the default error type for @specializes should be
used.

-- 
Configure bugmail: https://bugs.freedesktop.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug.
You are the assignee for the bug.