Damien Seguy wrote:
> According to Zend's site (http://www.zend.com/phpfunc/nodoku_alias.php),
> there is a bunch of undocumented functions which are only aliases.
> Docs says that, for instance, mysql() is still available for downward
> compatibility, but there is no entry for mysql() function.
> Is this done on any purpose?
Yes. Per discussions in Nov/Dec., some guidlelines were established.
>From /phpdoc/README:
> 1. Only major functions should be documented, functions which are
> deprecated variants may be mentioned, but should not be
> documented as separate functions. They instead should be
> referenced in the parent function as an alias. Functions which
> have completely different names, however, should be documented as
> separate entries, for ease of reference.
>
> Examples:
> mysql_db_name and mysql_dbname will be documented as the same
> function, with the latter being listed as an alias of the
> former.
>
> show_source and highlight_file will be documented as two
> different functions (one as an alias), as the names are
> completely different, and one name is not likely to be found
> if looking for the name of the other.
and:
> 3. Functions which are kept only for backwards compatibility should
> be listed under their current parent names, and not documented as
> separate functions. Backwards compatible functions and
> documentation for them should be maintained as long as the code
> can be reasonably kept as part of the PHP codebase.
Also, from /php4/CODING_STANDARDS:
> Aliases & Legacy Documentation
> -----------------------------------
> You may also have some deprecated aliases with close to duplicate
> names, for example, somedb_select_result and somedb_selectresult. For
> documentation puposes, these will only be documented by the most
> current name, with the aliases listed in the documentation for
> the parent function. For ease of reference, user-functions with
> completely different names, that alias to the same function (such as
> highlight_file and show_source), will be separately documented. The
> proto should still be included, describing which function is aliased.
>
> Backwards compatible functions and names should be maintained as long
> as the code can be reasonably be kept as part of the codebase. See
> /phpdoc/README for me information on documentation.
The reason for the above was mostly about giving the users a "right"
name for a function, without damaging our legacy codebase, or having
to keep many documentation pages in sync. If the function legacy name is
listed in the current name page, they can still find it via the
"search" interface.
Besides, we're far enough behind on functiuons with _no_ ducumentation,
let alone aliases, that we need to focus any new documentation efforts
on getting those names taken care of.
-Bop
--
--2D426F70|759328624|00101101010000100110111101110000
Personal: [EMAIL PROTECTED], 520-326-6109, http://www.opus1.com/ron/
Work: [EMAIL PROTECTED], 520-546-8993, http://www.pnsinc.com/
The opinions expressed in this email are not necessarily those of myself,
my employers, or any of the other little voices in my head.
