Annotated Fortran bindings

[angainor]

This is mostly meant as a discussion, as I don't know if this functionality is possible / simple to implement.

Currently the generated Fortran bindings have generic argument names arg<n>:

    type(c_ptr) function add(arg0, arg1) bind(c)
      use iso_c_binding
      type(c_ptr), value :: arg0
      integer(c_int), value :: arg1
    end function

The generated bindings are hence not user-readable: the user cannot simply look at the Fortran module to know how to use the bindings, and instead must go elsewhere to look for the meaning of individual arguments. Either the C++ source code, or the documentation.

One way to improve this would be to allow the programmer to define the argument names, e.g., in the BINDGEN_EXPORT_BINDING macro. For example

BINDGEN_EXPORT_BINDING_NAMED_2(add, add_impl, vector, new_element);

could generate the following interface

    type(vector_type) function add(vector, new_element) bind(c)
      use iso_c_binding
      type(vector_type), value :: vector
      integer(c_int), value :: new_element
    end function

In a similar way before the interface definition one could place a comment to briefly explain the usage:

    ! append an element to a vector
    type(vector_type) function add(vector, new_element) bind(c)
      use iso_c_binding
      type(vector_type), value :: vector
      integer(c_int), value :: new_element
    end function

[lukasm91]

// parentheses might help
BINDGEN_EXPORT_BINDING_2(add, add_impl, (vector, new_element),
    "append an element to a vector");
// or (args or desc could be optional in this case, I think)
BINDGEN_EXPORT_BINDING_2(add, add_impl, BINDGEN_ARGS(vector, new_element),
    BINDGEN_DESC("append an element to a vector"));

I would assume that we don't even need a new name for these, because we can detect the number of arguments to the macro.