Errors

[mardy]

Creates Error classes from XML annotations.

Adds an optional parameter to specify the namespace where the error classes should be generated, in case the default one creates conflicts.

[jonte]

Why not use the annotation format mentioned in https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format ?

Seems like we could do something like this:

<method name="Frobate">
    <arg name="foo" type="i" direction="in"/>
    <arg name="bar" type="s" direction="out"/>
    <arg name="baz" type="a{us}" direction="out"/>
    <!-- Documentation of error -->
    <annotation name="org.gdbus.codegen.glibmm.Error" value="MyCustomError"/>
</method>

Might want to pick a more clever annotation name though..

[mardy]

Why not use the annotation format mentioned in https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format ?

I think that this is a very good idea. For some reason, other toolkits didn't go this way, but I think we should give it a try. Maybe like this:

<!-- Error documentation -->
<annotation name="error" value="org.gdbus.codegen.glibmm.Error.MyCustomError">

Then I suggest that we mandate that this annotations should be made at the interface level, and not per method (you can still write the list of errors emitted by a method in a documentation comment): the reason is that we might find the same error mentioned in several methods, and the documentation line might be different, among these instances. It's a problem we have also in my solution, but I think that if we use the annotation keyword, then it's easier to solve it.

[jonte]

Why not use the annotation format mentioned in https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format ?

I think that this is a very good idea. For some reason, other toolkits didn't go this way, but I think we should give it a try. Maybe like this:

<!-- Error documentation -->
<annotation name="error" value="org.gdbus.codegen.glibmm.Error.MyCustomError">

Yes, something like that.. But I would also choose a descriptive "annotation name", to make it a bit easier to understand where this extension to the XML format comes from (our code generator).

If this annotation becomes popular enough, it could then be mentioned in the D-Bus spec, since we follow the naming format of other annotations ;)

EDIT: Oh, wait. Basically, I think we should keep the reference to the code-generator ("org.gdbus.glibmm.Error") (which is capable of correctly parsing the annotation) in the name= fields, and let value= be whatever the interface writer wants ("org.myproject.MyError"). Maybe that was your intention here as well?

Then I suggest that we mandate that this annotations should be made at the interface level, and not per method (you can still write the list of errors emitted by a method in a documentation comment): the reason is that we might find the same error mentioned in several methods, and the documentation line might be different, among these instances. It's a problem we have also in my solution, but I think that if we use the annotation keyword, then it's easier to solve it.

Yep. This makes perfect sense.

[jonte]

We could even use a different field than value= I guess, maybe error-name= to make it more clear that name= is the name of the annotation, and the second parameter is the name of the error.

[mardy]

Why not use the annotation format mentioned in https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format ?

I think that this is a very good idea. For some reason, other toolkits didn't go this way, but I think we should give it a try. Maybe like this:

<!-- Error documentation -->
<annotation name="error" value="org.gdbus.codegen.glibmm.Error.MyCustomError">

Then I suggest that we mandate that this annotations should be made at the interface level, and not per method (you can still write the list of errors emitted by a method in a documentation comment): the reason is that we might find the same error mentioned in several methods, and the documentation line might be different, among these instances. It's a problem we have also in my solution, but I think that if we use the annotation keyword, then it's easier to solve it.

We could even use a different field than value= I guess, maybe error-name= to make it more clear that name= is the name of the annotation, and the second parameter is the name of the error.

Unfortunately we cannot do this, because the DTD for the D-Bus XML files only admits name and value as attributes for annotations.

[jonte]

Looks great, I think. Can you also make an entry to the README explaining how the errors work?

I guess we need to add something similar to this:

--cpp-namespace=NAMESPACE A string to prepend to the namespaces of the generated functions.

And also maybe a note on the <annotation usage.