Bug 24941

Some more docs branches ready for review:

http://git.collabora.co.uk/?p=user/cosimoc/wocky.git;a=shortlog;h=refs/heads/doc-fixes

http://git.collabora.co.uk/?p=user/cosimoc/wocky.git;a=shortlog;h=refs/heads/doc-tls

http://git.collabora.co.uk/?p=user/cosimoc/wocky.git;a=shortlog;h=refs/heads/doc-fixes-connection-porter

Another useful branch is 

http://git.collabora.co.uk/?p=user/cosimoc/wocky.git;a=shortlog;h=refs/heads/dynamic_sections

I'd prefer it if you didn't stack code changes on top of documentation stuff.

doc-barecontact: ++

porter-doc:

> +   * @domain: error domain

I'd prefer this to say "@domain: error domain (a #GQuark)", but I can add that afterwards

> - * You can then call wocky_porter_force_close_finish() to get the result of
> + * You can then call #wocky_porter_force_close_finish to get the result of

Why? The former is the correct gtk-doc markup, I think?

> + * Handler called when a matchig stanza has been received by the

s/matchig/matching/

doc-contactfactory:

> + * Returns: an #WockyBareContact instance.

s/an/a/

> + * returns it in case it's found.

s/in case/if/

doc-xmppnode:

> Rebuild the sections automatically

This is a build-system change which doesn't stack well with others (I suspect it'll conflict with changes I made to add some missing stuff to sections.txt). I think it should be done separately, if at all. If done, dynamic_sections should be merged at the same time.

> Add docs for WockyXmppNode.

> + * @ns: a #GQuark

We can tell it's a quark by the type. :-P

A more useful comment would be "@ns: a quark corresponding to an XML namespace URN."

> + * wocky_xmpp_node_init:

Not an objection to this branch, but couldn't this be called automatically when needed?

doc-fixes: ++

doc-tls: I'll come back to this one

dynamic_sections: I'll come back to this one

configure_summary: this is Bug #24993

example_fix: this is Bug #24994

doc-fixes-connection-porter:

> + * Returns: %TRUE if the JID has been correctly decoded.

I'd prefer "... if the JID is valid", and indeed in a merged branch I wrote just that... I'll discard this change in favour of what I did in an already-merged branch.

http://git.collabora.co.uk/?p=user/smcv/wocky.git;a=shortlog;h=refs/heads/docs fixes my criticisms of Cosimo's branches, and some conflicts. It incorporates all of the stack of branches that ends with doc-fixes-connector, except for example_fix, configure_summary, dynamic_sections, doc-tls, and the commit "rebuild the sections automatically" from doc-xmppnode.

(In reply to comment #3)
> > Rebuild the sections automatically
> 
> This is a build-system change which doesn't stack well with others

More precisely, this is an architectural choice: do we hand-write the sections.txt, or let gtkdoc generate it?

Hand-writing the sections.txt means we can arrange things in whatever order makes most sense to us, and means we don't have to have a 1:1 mapping between header files and chapters in the documentation.

However, it increases maintenance - you have to remember to add things to -sections.txt. In telepathy-glib this is offset by having "make check" verify that -unused.txt is empty.

In docs for register_handler:

> ++ *  the stanza, or %TRUE to stop further processing and free the stanza.

The stanza isn't freed if you hold a ref to it. Do we need to explicitly say that you need to ref. the stanza if you want to hold onto it?

> + * Returns: %FALSE to stop further child from being examined.
> + */
> typedef gboolean (*wocky_xmpp_node_each_child_func) (WockyXmppNode *node,

should be children.

Otherwise ship it.

I've pushed two more patches to fix Will's comments.

Plot a course to merge island!

Fixed, (will be|is) in Gabble 0.9.8 I believe