Date: Wed, 5 Aug 1998 09:38:22 +0300 (IDT) From: Eli Zaretskii To: Nate Eldredge cc: djgpp-workers AT delorie DOT com Subject: Re: emu387 functions undocumented/undeclared In-Reply-To: <35C74C29.EBC9292E@cartsys.com> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Precedence: bulk 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 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.