[Ur] Clarifying public API

[Adam Chlipala]

On 12/21/18 11:01 AM, Benjamin Barenblat wrote:
> I’d like to change the way the liburweb API appears to consumers.
> [...] As I see it, there ought to be
> four categories of functions:
>
>    1. functions that are public for FFI purposes,
>    2. functions that are used in compiled code but should never be called
>       by FFI libraries,
>    3. functions that are internal to the runtime but need to be called
>       across translation units, and
>    4. static functions.
That sounds like a reasonable categorization.  I hadn't mentally 
distinguished too much between categories 2 and 3, but otherwise this 
system matches my thinking.
> I think only public functions (category 1) should be listed in urweb.h.
> Functions needed by compiled code but not available for the FFI
> (category 2) should go in their own header file, and to emphasize their
> internal nature, we shouldn’t install that header in /usr/include but
> rather in /usr/share/urweb. Internal functions needed across translation
> units (category 3) should be declared in headers that are only used
> while compiling the runtime and not installed at all.
I could go along with that.  My current model is that the manual lists 
all category-1 functions, though I may have missed some that belong 
there.  As for physically separating categories across header files, I 
see the benefit of more detail/encapsulation conveyed by 
machine-processed documentation (headers).  I also see the downside of 
added complexity in compilation and use of the file system.
> The major challenge here is figuring out exactly what the public API
> should be. What functions and types should we expose to FFI consumers?
See last paragraph of my answer.  I have always thought the manual 
already answers this question, and it's a documentation bug if not.
> But do FFI libraries really need to call, say,
> uw_Basis_strlen, when there’s a perfectly reasonable strlen in libc that
> does the same thing?
No, they shouldn't, and that's why I didn't list any 'uw_Basis_*' 
functions in the manual.  However, you picked a funny example, since 
things have recently been getting interesting there, with support 
(mostly by Fabrice Leal) for internationalization in the runtime 
system!  As a person unfamiliar with how all that business works, I 
might indeed be tempted to call uw_Basis_strlen from C FFI code!