Date: Fri, 12 Oct 2001 14:31:29 +0200
From: "Eli Zaretskii" <eliz AT is DOT elta DOT co DOT il>
Sender: halo1 AT zahav DOT net DOT il
To: "Eric Botcazou" <ebotcazou AT libertysurf DOT fr>
Message-Id: <4098-Fri12Oct2001143129+0200-eliz@is.elta.co.il>
X-Mailer: Emacs 20.6 (via feedmail 8.3.emacs20_6 I) and Blat ver 1.8.9
CC: djgpp-workers AT delorie DOT com
In-reply-to: <00a201c152ff$9fe975a0$180b24d5@zephyr>
	(ebotcazou AT libertysurf DOT fr)
Subject: Re: _findfirst() patch
References: <10110111357 DOT AA18726 AT clio DOT rice DOT edu> <006601c15277$3736ab00$d27824d5 AT zephyr> <1659-Thu11Oct2001211157+0200-eliz AT is DOT elta DOT co DOT il> <00d901c152a0$398d6fa0$845824d5 AT zephyr> <7458-Fri12Oct2001003417+0200-eliz AT is DOT elta DOT co DOT il> <018a01c152ad$8f5ad8c0$845824d5 AT zephyr> <4331-Fri12Oct2001084812+0200-eliz AT is DOT elta DOT co DOT il> <00a201c152ff$9fe975a0$180b24d5 AT zephyr>
Reply-To: djgpp-workers AT delorie DOT com
Errors-To: nobody AT delorie DOT com
X-Mailing-List: djgpp-workers AT delorie DOT com
X-Unsubscribes-To: listserv AT delorie DOT com
Precedence: bulk

> From: "Eric Botcazou" <ebotcazou AT libertysurf DOT fr>
> Date: Fri, 12 Oct 2001 11:20:06 +0200
> 
> > Right, except that findfirst was there first, and _dos_findfirst
> > didn't seem like an important addition, so I guess no one looked very
> > hard inside it.
> 
> May I say that's for me the limit of the 'one external function per file'
> rule ? Instead of having one core code in one location privately shared by
> multiple interfaces, you end up with multiple core codes with their own
> interface or single core codes publicly shared by multiple interfaces (see
> below).

Sorry, I don't understand what did you try to say here.

If it helps, _dos_find* functions are indeed a deviation from what I
consider a good design.

> Ok, but the 'one external function per file rule' leads precisely to make
> external functions of helper functions: the three low-level wrapper
> functions I proposed are IMHO helper functions that shouldn't be exposed to
> the public. Now they are exposed to the public: should I document them
> anyway, given that the user will be already faced with no less than three
> sets of find*() functions ? Won't a fourth set of find*() functions confuse
> him ?

I think we should document everything that applications can possibly
use.  You never know what will they need or want, so let's not
second-guess them.

As for confusion--it's okay to tell in the docs something like "This
function is supposed to be called internally by the function `xyzzy';
do _not_ call directly!"  Once we say that (if it's really true in
this case--I'm not necessarily saying it is), it's up to the users to
do what they see fit.

> > An external function is something that functions in other modules can
> > call.
> 
> So either a function is private to a module (static) or publicy exposed and
> documented (external) ?

Minor correction: public functions _should_ be documented, but some of
them aren't (we are not perfect ;-).  Those cases where there's no
docs are considered bugs, though.

> Isn't there any room for functions private to the library (non
> static, non publicy exposed and non documented in a .txh file but
> only in their source file) ?

As I said: functions which aren't supposed to be called by
applications should say so in their docs.