Mail Archives: djgpp-workers/2001/10/12/08:32:54
> 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.
- Raw text -