Mail Archives: djgpp-workers/1998/08/05/02:38:44
On Tue, 4 Aug 1998, Nate Eldredge wrote:
> The functions in the emu387 tree of libc aren't documented, and also
> aren't declared in any headers. The major one of interest is
> `_detect_80387'; there is also `_npxsetup' and a few globals. I will
> write the docs, but what header should they go in (if any)?
I suggest <dos.h> for `_detect_80387', since that's where the _8087
global variable is declared in TC and BC. And while at that, how
about adding _8087 as well?
Btw, if you document `_npxsetup', it should have a large WARNING
written all over it, saying that an application shouldn't call it. It
is nothing but trouble (look at the source and you will understand),
and I cannot imagine why somebody will ever need that.
> Also, what is the policy on documentation of functions? libc.inf says
> it documents "all public symbols", but that's not really the case. Some
> public symbols are internal to the library and completely useless to an
> application. (Examples: __crt1_startup, and the dummy
> __emu387_load_hook.) Should we document them, if only to say "internal
> to libc, don't use"?
Personally, I think that everything should be documented. The reason
is that, given a good index in libc.info, a user can look up relevant
functionality in a centralized place. Without that, the only option
is to grep the library sources (or use ID-utils) which leave no real
clues about the purpose of these facilities except what their names
tell.
That said, I'm not the one who makes policy decisions around here.
In practice, I would first worry about documenting *useful*
functionality, like the `end' symbol, before we get to documenting the
rest of them.
- Raw text -