Bug 15464

Summary: Telepathy-glib should link enums in the documentation
Product: Telepathy Reporter: Olivier CrĂȘte <olivier.crete>
Component: tp-glibAssignee: Telepathy bugs list <telepathy-bugs>
Status: RESOLVED FIXED QA Contact: Telepathy bugs list <telepathy-bugs>
Severity: enhancement    
Priority: medium Keywords: patch
Version: unspecified   
Hardware: Other   
OS: All   
URL: http://git.collabora.co.uk/?p=user/jonny/telepathy-glib.git;a=shortlog;h=refs/heads/client-gen-guint
Whiteboard:
i915 platform: i915 features:

Description Olivier CrĂȘte 2008-04-11 17:57:42 UTC
Various telepathy-glib functions have arguments that are defined by enums. It would make the documentation much more useful if the arguments to these functions was the name of those enums insteads of being just "guint".
Comment 1 Simon McVittie 2008-04-30 09:45:47 UTC
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.
Comment 2 Robert McQueen 2008-05-19 17:45:33 UTC
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?
Comment 3 Simon McVittie 2008-05-20 02:29:17 UTC
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).
Comment 4 Murray Cumming 2008-10-29 02:48:18 UTC
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.
Comment 5 Jonny Lamb 2011-01-06 02:48:22 UTC
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?
Comment 6 Will Thompson 2011-01-06 03:41:21 UTC
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.
Comment 7 Jonny Lamb 2011-04-27 07:39:51 UTC
(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?
Comment 8 Will Thompson 2011-04-28 09:58:02 UTC
Yeah, let's do this.
Comment 9 Jonny Lamb 2011-05-02 01:02:57 UTC
Neat.

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.