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