Bug 15464

Changing the actual types of the arguments is WONTFIX (we have an API/ABI already and we should stick to it). I agree that ideally the generated documentation would point to the appropriate enum with a hyperlink, but in practice this is harder than you'd expect due to the way everything's generated.

Is changing the generation to refer to the right enums actually an API break in C? I thought you could move between enums and uints freely?

Strictly speaking, C enums are equivalent to *signed* ints.

Unless I do some heavy refactoring of the code-generation stuff so that everything comes out of the same script, this isn't hugely feasible to do... the service and client bindings can't reliably know where the enums came from, and thus whose API prefix they have (at least in extensions; telepathy-glib could perhaps get a special case).

Here is an example, by the way:
http://telepathy.freedesktop.org/doc/telepathy-glib/telepathy-glib-connection.html#tp-cli-connection-signal-callback-status-changed
It uses a guint instead of ConnectionStatus and doesn't link ConnectionStatus in the documentation.

So, without something like specparser, this is actually really hard because once you see you have a guint argument you don't know whether it is actually a number (like number of handles, or avatar height, etc.) or it is an enum.

I've written a patch to fix this in the client codegen. It displays the type in the gtk-doc for guint arguments if there's a tp:type.

There is a problem here though. Because we don't know whether a guint is part of an enum or whether it's a number on its own, we get nice links like #TpConnectionStatus (yay), #TpHandle (yay), and #TpContactHandle (boo).

The latter will just not get linked by gtk-doc, and tbh I think this is acceptable. We can fix this properly when we break ABI.

Thoughts?

Are there any places where we have enums/flags for non-uints? I think this would be a net improvement. It doesn't remove information; and I don't think the cost of unlinked types kicking around outweighs the benefits.

I do note that Murray's example will become:

arg_Status : An integer indicating the new status, as defined by ConnectionStatus (#TpConnectionStatus)

So there could perhaps be some cleanup of the spec afterwards.

(In reply to comment #6)
> Are there any places where we have enums/flags for non-uints? I think this

    <tp:enum name="DTMF_Event" type="y">

so this appears as a guchar. Tempted to say "don't care" though?

There are no flags which don't use type="u", and there was an unused enum in Location which I just fixed.

So, mergey?

Yeah, let's do this.

Neat.