delorie.com/archives/browse.cgi   search  
Mail Archives: djgpp-workers/1998/08/05/02:38:44

Date: Wed, 5 Aug 1998 09:38:22 +0300 (IDT)
From: Eli Zaretskii <eliz AT is DOT elta DOT co DOT il>
To: Nate Eldredge <nate AT cartsys DOT com>
cc: djgpp-workers AT delorie DOT com
Subject: Re: emu387 functions undocumented/undeclared
In-Reply-To: <35C74C29.EBC9292E@cartsys.com>
Message-ID: <Pine.SUN.3.91.980805093803.11089H-100000@is>
MIME-Version: 1.0

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 -


  webmaster     delorie software   privacy  
  Copyright © 2019   by DJ Delorie     Updated Jul 2019