At 01:15 10-09-01, Egon Schmid wrote:
> > Not writing documentation is certainly within your right, but this is a
> > poor argument for not doing so. Certainly a main reason that people
> > code from examples and not documentation is when documentation is poor.
>
>Sorry, couldn't resist. The documentation is poor, when the authors
>don't write.
I don't think that's true (most of the documentation in the world is not
written by the code authors but by technical writers), but if it is true,
then we're screwed.
> It is also very bad not even read the documentation.
Like I told George, I don't make a religion out of what I do, that is, I'm
not saying that anything I (or other developers) do is perfect. I just say
that's the way things *are*. In a perfect or even a better world, they may
have been different.
Fact is that developers usually don't like to write documentation (there
are exceptions, some people do, and even I like to write docs/articles
every once in a while). And an equally sad fact you raised, is that many
of them don't even like reading documentation. I agree it's far from being
ideal.
>Zeev
>please let us stop this thread and others also. You will never gain a
>popularity if you will deprecate a popular function such as _() from the
>gettext extentsions and the documentation.
If I was after popularity I'd be making populist statements, definitely a
proven method. I say what I think is best for the language, within (what I
believe to be) reasonable negative limits. If I and some others were going
after popularity, PHP would have been full of all sorts of features from
all sorts of languages, and IMHO, would have been dead in the water by now.
Egon - FWIW, _() is documented much less documented than the Zend engine
(which I, as someone who believes it should be deprecated, think is a good
thing), and even that is an insult to the Zend Engine docs (which were
fairly thorough, and just weren't updated).
You said it's an alias, and thus doesn't appear in the docs. How is
somebody reading a PHP file that has
print _("Thou shalt not obscure");
supposed to have a clue what the heck it is?
If not documenting aliases is a guideline, that it applies almost equally
to those other aliases (almost, because _() looks like language magic, and
I'm not sure how many people would look it up as a function name).
The way I see it, undocumented aliases *are* a way to deprecate a
function. In my opinion, _() *is* undocumented in the sense that I cannot
find what it is, unless I happen to stumble upon the documentation for
gettext(). Again, this may be true for other aliases.
Zeev
--
PHP Development Mailing List <http://www.php.net/>
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
To contact the list administrators, e-mail: [EMAIL PROTECTED]
