Re: Few questions when documenting

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