Errors and the introspection format

[Matthew Johnson]

On Fri, 17 Feb 2006, Havoc Pennington wrote:

> On Fri, 2006-02-17 at 18:11 +0000, Matthew Johnson wrote:
>> So, Java will expose this in the programming API, and everything else will just
>> list it as another annotation, this is fine, but the introspection data should
>> contain all the API, and this includes error conditions.
>
> The most important part of the API is the semantic documentation of the
> method's contract. i.e. what happens when you call the method.

I agree and I think that what errors can be thrown is a vital part of
that contract exactly as much as what signals can be sent.

> Every language but Java includes "what errors are thrown" in the docs,
> rather than the method signature. I like the Java way, but the unchecked
> exception way does work fine. There are already a ton of other features
> of any given ABI that depend purely on docs and aren't checked by the
> compiler. It's not like this is the only one.

The introspection data is where I would look for the raw semantic
documentation for what types (including types of errors) the application
sends and receives. It would be nice (see other thread on Description
annotations) to have short descriptions of things at least at the method
level as well. The number of times when working with DBus I have been
told to 'look at source file X' because the docs aren't up to date, it
would be really nice to have this stuff available from the code (people
are marginally more likely to keep this up to date, if nothing else).

DBus has a great self-documenting system for the APIs, if you include
exceptions and possibly a short description, it would be *really*
*really* good, and contain everything I can think that I would like to
know. With the aid of the XSLT I posted to the list a couple of days ago
you can even generate nice javadoc-like webpages from it.

> If the Java bindings think that dbus method signatures include the
> exceptions thrown, and no other bindings think that, it's just going to
> cause interoperability problems IMO.
>
> A non-goal of dbus is to be able to round-trip any native type or method
> for a given framework. i.e. dbus is deliberately closer to the
> intersection of the bindings' type systems, than to the union of them.

But you have introduced the notion of typed exceptions; and since you
have please please can you let those languages which support them use
them. I don't mind it just being an annotation which other bindings just
pass through and don't do anything at the language level and I don't
mind if it is only SHOULD or RECOMMEND rather than MUST, but I definitely
do not believe there will be interoperability problems and I do believe
that it will benefit all programmers of clients due to having them
written down at the top of the function. It will benefit languages like
Java which encourage explicitly declaring throws, it will benefit
language which don't but still can throw typed exceptions. I wouldn't
mind so much if I can dynamically create new types, but I can't, they
have to be done at compile time so it would be extremely helpful if it
were in the automatic compile time data I have.

Matt

-- 
Matthew Johnson
http://www.matthew.ath.cx/