php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #76031 Several ext/stats functions are documented incorrectly
Submitted: 2018-02-28 20:19 UTC Modified: 2021-11-16 13:19 UTC
Votes:2
Avg. Score:3.0 ± 0.0
Reproduced:1 of 1 (100.0%)
Same Version:1 (100.0%)
Same OS:1 (100.0%)
From: dustin dot glidden at gmail dot com Assigned:
Status: Suspended Package: stats (PECL)
PHP Version: 7.2.2 OS: linux
Private report: No CVE-ID: None
 [2018-02-28 20:19 UTC] dustin dot glidden at gmail dot com
Description:
------------
---
From manual page: http://www.php.net/function.stats-rand-gen-int
---

stats_rand_gen_int has changed to stats_rand_ignlgi


Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2018-02-28 22:31 UTC] cmb@php.net
-Package: Documentation problem +Package: stats
 [2018-03-01 21:05 UTC] philip@php.net
-Summary: this function no longer exists +Summary: Several ext/stats functions are documented incorrectly -Status: Open +Status: Verified
 [2018-03-01 21:05 UTC] philip@php.net
It appears this was always the case, and that the prototype was wrong in the source code for the stats_rand_ignlgi function for about 10 years.

The stats documentation was probably generated via a tool that read source prototypes (our tools used to use prototypes long ago when generating doc skeletons, but now we have doc-base/scripts/docgen/ uses Reflection data instead).

Here is the bug report that reported the incorrect prototype: 

  name mismatches in statistics.c (September 11, 2007)
    https://bugs.php.net/bug.php?id=57832

And the patch that fixed this prototype and many others in the stats extension:

  Fixed inconsistent prototype declarations (May 24, 2016)
    https://github.com/php/pecl-math-stats/commit/900275fb3f84cca3dac574182e9f185602a42c53

While Bug #57832 requested stats_rand_ignlgi() be renamed to stats_rand_gen_int() to match the prototype, that is not what happened, probably because the fix was ~8.5 years later and didn't want to break backwards compatibility by renaming a bunch of functions.

Because commit 900275fb3f84cca3dac574182e9f185602a42c53 changed many prototypes, the odds are high that many other stats functions are incorrectly documented and not only stats_rand_ignlgi(). For this reason this bug report is being hijacked to compare and fix all stats functions here:

  http://php.net/manual/en/ref.stats.php

There are several tools in doc-base/ that could help this cause, and if one does not exist for this then it probably should. It might compare the source code, PHP documentation, and the extensions Reflection data, and make sure all three are the same. Sorry for digressing but this was fun to research :)

With all that said, if someone decides to only change stats_rand_gen_int() to stats_rand_ignlgi() in the docs then that's okay, please report the fix here but leave the bug report open until all of stats is evaluated.
 [2019-04-01 11:50 UTC] dmitriy dot shashkin at gmail dot com
Same problem with function "stats_rand_gen_ibinomial" that was renamed to "stats_rand_ibinomial".
 [2021-11-16 13:19 UTC] cmb@php.net
-Status: Verified +Status: Suspended
 [2021-11-16 13:19 UTC] cmb@php.net
Sorry to say, but the stats extension is unmainted, and its
documentation has been removed from the PHP manual.  Therefore I
suspend this ticket, until a new maintainer steps up.
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Sat Oct 05 00:01:29 2024 UTC