Bug 35117

Summary: Make gtk-doc nicer
Product: Wocky Reporter: Jonny Lamb <jonny.lamb>
Component: GeneralAssignee: Telepathy bugs list <telepathy-bugs>
Status: RESOLVED FIXED QA Contact: Telepathy bugs list <telepathy-bugs>
Severity: normal    
Priority: medium Keywords: patch
Version: unspecified   
Hardware: Other   
OS: All   
URL: http://cgit.freedesktop.org/~jonny/wocky/log?h=gee-tee-kay-doc
Whiteboard: review+
i915 platform: i915 features:

Description Jonny Lamb 2011-03-08 07:51:04 UTC
I spent some time making the documentation of Wocky nicer.

I've mostly just documented things that were only half-done, thus making the output of running the gtk-doc rules a lot less verbose. I only upped the coverage from 39 per cent to 45 per cent, but it's better than nothing.
Comment 1 Will Thompson 2011-03-08 10:39:36 UTC
+ * @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.
Comment 2 Jonny Lamb 2011-03-09 03:25:20 UTC
(In reply to comment #1)
> I think the parenthetical statement confuses more than it adds.

Okay, removed.

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

Yes, why didn't I do that before? Done.

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

Done. I naively cloned the gtk-doc repository but that's as far as I got...

> + * @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.

Ah, I see.

All updated and pushed.
Comment 3 Will Thompson 2011-03-10 03:42:52 UTC
shippitâ„¢

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.