Include service-defined exceptions in introspection data (Was Re: glib bindings (Was Re: [patch] gobject sender and pid))

[Havoc Pennington]

Hi,

On Tue, 2006-03-14 at 20:08 -0500, David Zeuthen wrote:
> On Tue, 2006-03-14 at 13:38 -0500, Havoc Pennington wrote:
> > On Mon, 2006-03-13 at 23:28 -0500, David Zeuthen wrote:
> > > There is no good solution on how to document D-BUS methods yet; where's
> > > the support in Doxygen or gtk-doc? This is actually a problem we ought
> > > to solve too :-)
> > > 
> > 
> > Sure, let's do it ;-)
> 
> But how? Ideally existing tools such as Doxygen, gtk-doc would just take
> the introspection XML and do it's thing. If introspection data don't
> include this how do you propose we get at it?

You mean get at the @throws? It's just in the docs themselves wherever
those are, same as for Java or gtk-doc or Doxygen. I would propose the
docs themselves should live wherever the "canonical" interface
definition lives; referring to the other discussion for a minute, I
expect that will frequently be the implementation source code of the
server. But if someone wanted to have the XML or IDL canonical and
generate both client and server code from it, the docs would go in the
XML or IDL file.

As discussed on prior occasions, though, probably a runtime Introspect()
wouldn't return the docs, or they'd only be returned optionally, or
something like that.

> > > And I still maintain that what exceptions a method throws is part of the
> > > ABI and parts of HAL even rely on this [1]. Thus, it's pretty useful for
> > > tools that does ABI checking; for example some enterprise Linux vendors
> > > actually checks this when providing upgrades to customers. So if someone
> > > wants to update HAL in from RHEL8 to RHEL8U1 and the new HAL now throws
> > > SomeNewException on the method Foo on interface Bar there's an easy way
> > > to catch this. This is preferable to just seeing (badly written)
> > > application XYZ crash or misbehave.
> > 
> > Structured docs 
> 
> Nice. So if I'm a vendor I need to make my test system understand all
> sorts of "structured docs"?!?

Well, several points:
 1) I think the danger of bindings authors changing generated code 
    depending on a throws annotation, or programmers in general thinking
    the throws is in the "type system," is larger than making the LSB 
    jump through a minor hoop
 2) structured docs need not be any different from a "throws clause" 
    in difficulty of using/parsing, just a matter of tools
 3) there's no way to test this anyhow - you could detect a documented
    ABI break, but not an undocumented one - how would your test suite
    trigger throwing an exception that didn't used to exist?
    So in this case we may as well assume there are docs, and that they
    are accurate both before and after. Whether the docs are @throws 
    or a "throws keyword" is really not important that I see.

> > should enable the same, though, without misleading
> > people into thinking the exception stuff is part of the type system or
> > should be reflected when generating bindings.
> 
> Do you disagree that what exceptions _a service_ may throw is part of
> the ABI for that service? 

There are two things involved in ABI with distinct implications:
 a) the stuff that a programming language cares about and type checks
 b) the "semantics" that exist only in the docs

If I make gtk_widget_show() into a no-op, then I've broken b) but not
a).

All programming languages except Java (sometimes, when using checked
exceptions) put exceptions in category b).

That's why I think dbus should put them in b) also. It will make a mess
if exceptions are in a) "sometimes" (where "sometimes" is basically
undefined, since who knows what binding authors will do)

Putting exceptions in b) simply sets a more accurate expectation, while
making no real functional difference. For Java this info should be in
@throws not the method declaration for dbus methods. For every other
language, it doesn't even matter. Seems simple enough.

Havoc