[boost] [function_types] documentation issues

Subject: [boost] [function_types] documentation issues
From: Sam Partington (sam.partington_at_[hidden])
Date: 2009-08-06 06:50:33

Hi all,

I am writing a library that aims to make using dynamic libraries
easier across platforms.  The aim is the following :

 dynamic::library lib("sharedlib.so");
 dynamic::function<int (int, int> fn(lib, "fn");
 int result = fn(1, 2);

So to achieve this I needed to implement forwarding functions and I
used function_types to make this easier.  This all worked fairly well,
but in general I really struggled with figuring out how to use
function_types.  Though simple uses were fairly straight forward, as
soon as I came across a STDCALL function it all fell over and I got
compiler errors "'value' : is not a member of
'boost::function_types::function_arity<T>".

I have managed to fix it, but the route there was far from obvious,
and I would put that entirely down to incomplete and misleading
documentation.

Eventually, I found the Reference->Macros section which discussed
calling conventions :

BOOST_FT_CC_*

  Enables a specific calling convention. * dentoes the macro suffix,
as defined by BOOST_FT_CC_NAMES or BOOST_FT_BUILTIN_CC_NAMES.

  The macro expands to a list of restrictions, separated by the |
character. Possible items are:
     callable_builtin
     member
     non_member
     variadic
     non_variadic

  If no such macro is defined for a particular calling convention, it
is disabled. Example:
  #define BOOST_FT_CC_STDCALL non_variadic|callable_builtin
  // enables stdcall calling convention for all non-variadic,
  // callable, builtin types

Ahah!  It looked like I needed to #define BOOST_FT_CC_STDCALL
non_variadic|callable_builtin, as per the example there.  However this
caused monstrous compile errors from the guts of function_types
initially stating that "'...' requires cdecl".

Further reading pointed me to this :

BOOST_FT_COMMON_X86_CCs

  Defining this macro causes the following macros to be defined, if
not defined already:
  #define BOOST_FT_CC_CDECL BOOST_FT_COMMON_X86_CCs
  #define BOOST_FT_CC_STDCALL non_variadic|BOOST_FT_COMMON_X86_CCs
  #define BOOST_FT_CC_FASTCALL non_variadic|BOOST_FT_COMMON_X86_CCs

So I added the following :

#define BOOST_FT_COMMON_X86_CCs

But this also failed with more bizarre errors, eventually I experimented with :

#define BOOST_FT_COMMON_X86_CCs 1

Which finally worked.  But the docs do not indicate that you need to
define it with any particular value.

The whole problem would have been so much simpler if there was one of
more of the following sections in the documentation :  "Getting
Started", "Calling Conventions", "Common Pitfalls", or an FAQ.

Sam