Identifying what's usable in installed headers [was Re: RFC: Foreign objects facility]

[Doug Evans]

On Sun, Apr 27, 2014 at 6:17 AM, Andy Wingo <address@hidden> wrote:
> Hi,
>
> SMOBs have a few problems.
>
> [...]
>   7) There is legacy code out there that uses e.g. SCM_SETCDR to set
>      smob fields.  (This is terrible, but it exists:
>      https://github.com/search?q=SCM_SETCDR+smob&ref=cmdform&type=Code
>      for an example.)

Hi.
While it's on my mind I thought I'd write it down.

While function declarations are markable as being internal/external in
published headers (SCM_INTERNAL vs SCM_API), macros are not.
IWBN to solve this problem for macros too.  If it's in a header and a
user can get it to work, s/he may just use it - some macros are indeed
usable, so how does one easily know while reading headers (users will
do that a lot) which are legitimately usable and which are not?

There are various ways to solve this, I don't have a strong opinion on
that, but IWBN to solve it.
Setting aside moving internal things to separate headers (which feels
more expensive than it's worth), one could just wrap them in
appropriate #ifs.

[P.S. I'm not sure if SCM_SETCDR is still intended to be usable, I
wouldn't mind deprecating it, and only publishing the function
versions.  I can imagine it being ubiquitous enough in existing code
that that's not possible, even if one wanted to.  At any rate that's a
separate discussion.  Its presence in the foreign object discussion
just reminded me of macros in headers.]