IDL language

[David Zeuthen]

On Mon, 2009-05-11 at 16:39 +0100, Simon McVittie wrote:
> On Mon, 11 May 2009 at 09:59:56 -0400, David Zeuthen wrote:
> > On Mon, 2009-05-11 at 14:36 +0100, Simon McVittie wrote:
> > > > The D-Bus spec says to use CamelCase (actually it says WindowsStyleCaps)
> > > > and the existing message bus and standard interfaces already use that
> > > > naming convention. Would it be a big problem to just add an annotation
> > > > for these corner case, say, 
> > > > 
> > > >  @NamingHint ("Send_DTMF")
> > > >  SendDTMF (int32 stuff, ...)
> > > 
> > > That's fine for the bits where a convention exists (method names, signal names,
> > > properties) - 
> > 
> > Interface names too.
> 
> To an extent, the interface name has two uses anyway - there's the part used
> on D-Bus only, and the part used both on D-Bus and in the binding. For instance,
> org_freedesktop_telepathy_connection_interface_aliasing_call_get_aliases() is
> far too long
> 
> The hack we use in the Telepathy XML extensions is to set the <node> name
> (which is otherwise meaningless in introspection XML used as a pseudo-IDL) to
> "/Connection_Interface_Aliasing", as a hint to append that to the prefix in
> the C code (in practice we get tp_cli_connection_interface_aliasing_... which
> is still uncomfortably long, we should perhaps have used "conn" and "iface").
> 
> With hindsight, this should have been an attribute on the <interface> rather
> than an abuse of the <node> name.
> 
> >  a) it seems bizarre to have different conventions for interfaces and
> >     structs/enum and maybe a third convention for stuff we add later
> 
> What I was advocating was that this would be the convention for all new stuff,
> since it contains all the information needed by any case convention I can
> think of.
> 
> >  b) we can make the GLib code generator just fail if it's unable to
> >     find a NamingHint and if there is no suitable way of inferring it
> >     [1] and something like --infer-naming-hints were not given.
> 
> I'd prefer not to have --infer-naming-hints at all, if that argument means
> "guess wildly in the presence of multiple capital letters".

That kinda depends on whether the generated code is going to be public
API or not.

Sidebar:

  Btw, my view is that in an ideal world, generated code shouldn't
  be public API. Users (which would be applications, not libraries)
  would just generate D-Bus bindings part of their internal API.
  E.g. to use Telepathy or DeviceKit-disks, I'd just suck in the
  typelibs and generate code directly in my application and then I'm
  done.

  Of course this view isn't really tenable in the real world insofar
  that it's often desirable to have local code running in the client.
  For example, in Telepathy you need that to update your chatroom
  property (an array of chatroom participants) because you want avoid
  PropertyChanged on that sucker so you'd need code handling custom
  signals to convey what could have been a PropertyChanged signal.
  So it makes sense to extend the generated code to handle that and
  offer that as library API to Telepathy users. So the library API
  would include some generated code (that you extended as well).

  Ditto, in DeviceKit-disks, the D-Bus service only models block
  devices so in gnome-disk-utility I have code for figuring out what
  the drives, volumes and activatable drives are (and e.g. find
  components for drives not yet activated cf. Linux MD raid). So e.g.
  gnome-disk-utility will probably end up exposing some porting of
  the library API that is generated by a code generating.

  And, just, FWIW, I suffer from this issue too, e.g. I have acronyms
  such as RAID that I need the Ugly_Case stuff for too.

But for simple stuff (I would argue neither DeviceKit-disks or Telepathy
are simple services), just sucking in bindings as internal API to the
application should suffice. So I think --infer-naming-hints is warranted
since people generally don't care. Then again, I've got no strong
feelings on this.. maybe we just don't export that option. I'm fine with
that. If it turns out it's a giant pain in the ass for non-library
users, we can always add it.

> > We can also make the proposed dbus-validate-typelib(1) tool actually
> > error out (or warn) if there is no @NamingHint annotation for
> > problematic names (e.g. those with two capitals following each other).
> 
> Requiring an explicit naming hint (in the IDL, or on the command line, or in
> some helper file) for names with two consecutive capitals seems a reasonable
> compromise if you want to use CamelCase throughout.
> 
> Because this IDL is new, I don't think it would be unreasonable to make this a
> hard requirement in general - there's no installed base to be
> backwards-compatible with, and you are still defining the language, so you
> might as well define it in such a way that problematic usages are forbidden.

Sure, I think the IDL compiler should just error out if you omit the
@NamingHint annotation for problematic names. I've got no problem with
adding such a feature; I'm a big fan of whining compilers ;-)

But keep in mind that people will use lots of other tools for generating
typelibs (gobject-introspection, Java, hand-write them, whatever) so in
general it's hard to guarantee that you have a @NamingHint annotation
for a problematic name. In that case we'll just bail out in the GLib
code generator and let the user fix things up.

     David