Buesching, Logan J wrote:
1.) I had a couple questions on what the standard or “best practice” for
documenting a few things.
When I see something in the source code that is:
RETURN LONG(val);
But I notice that when I do gettype($val), it is actually an integer.
Maybe I’m missing something? Does it return a long when it needs to be
a long and an integer when it can fit into an integer? And if it’s the
ladder, how should I document that? Should I document it saying
“returns an integer” or “returns a long” or how else?
PHP integers are C long internally, and PHP floats are C doubles.
As PHP doesn't distinguish between different integer and float
subtypes the longest portable C types were chosen for both.
This wastes a tiny bit of performance and storage space but
you won't use PHP for heavy duty number crunching anyway,
would you? ;)
2.) At the bottom of all the XML sheets, it says
“sgml-default-dtd-file:../../../../manual.ced”… where is that file, or
if it has moved, where to? If it has moved, should I also update all of
my files to reflect those changes?
This is a helper file for Emacs PSGML mode. If you are using Emacs
you can generate it using "Parse DTD" and "Save DTD" from the
PSGML mode DTD menu. If you are not using Emacs you can ignore
that setting.
3.) There are a few things that are compiled conditionally and I was
wondering about how to document them. In the function with
posix_getpgid it says that it always returns false if the system doesn’t
support it. Is that true? Because it looks as though it doesn’t even
create a PHP function for it if it even exists:
*#ifdef* HAVE_GETPGID
PHP_FUNCTION(posix_getpgid)
{
*long* val;
*if* (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", &val)
== FAILURE) {
RETURN_FALSE;
}
*if* ((val = getpgid(val)) < 0) {
POSIX_G(last_error) = errno;
RETURN_FALSE;
}
RETURN_LONG(val);
}
*#endif*
* *
I would assume that if you don’t have it, then you don’t even get the
PHP function, but maybe, once again, I’m missing something?
Somewhere around PHP 4.0 or 4.1 we decided that functions depending
on features not available at compile time should not be compiled
in at all instead of always returning false so that PHP userland
code can simply test for such optional features using function_exists()
checks. Looks as if this is one of the functions that got changed
and the documentation was not updated along with that.
--
Hartmut Holzgraefe, Senior Support Engineer .
MySQL AB, www.mysql.com
