php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Request #72334 Link(s) to view the relevant PHP C source code in the documentation
Submitted: 2016-06-04 15:56 UTC Modified: 2016-06-06 16:59 UTC
Votes:2
Avg. Score:3.0 ± 2.0
Reproduced:1 of 2 (50.0%)
Same Version:0 (0.0%)
Same OS:0 (0.0%)
From: webmaster_20160604 at cubiclesoft dot com Assigned:
Status: Open Package: Documentation problem
PHP Version: Irrelevant OS: N/A
Private report: No CVE-ID:
Have you experienced this issue?
Rate the importance of this bug to you:

 [2016-06-04 15:56 UTC] webmaster_20160604 at cubiclesoft dot com
Description:
------------
One of the greatest sources of frustration in PHP is the disconnect between the documentation and the actual C source code.  I personally keep a copy of the PHP C source code handy for searching purposes but I know I'm in the minority and, even then, I rarely crack it open because doing so requires overcoming certain mental inertia.  I also have observed a general disdain of PHP userland developers on the internals list because userland devs don't look at/understand the C source code.

Let's try to fix this.  If each page of the documentation linked back to the relevant C source code (e.g. via an online git viewer), userland devs might actually click those links and learn how PHP works behind the scenes.  It that happens, it has great potential to both massively boost the number of people working on the core and dramatically reduce the amount of noise on bugs.php.net.  At the very least, it would raise awareness of how each built-in function, method, and class actually works, which is better than people *guessing* as to how they work in comments and forums across the Internet and on php.net itself.  Nothing is more frustrating than to see someone incorrectly guess how a software product works when the source code to that product is readily available.

I realize linking back to the C source code from the documentation is a fairly involved task.  A new documentation section would have to be standardized upon, every page of the XML source would have to be updated to add the section, and then every change verified.  Keeping the links in sync with the main source code could be a challenge as well.  It might also require tagging the core with some sort of common format, which would, of course, cause no small upheaval on the internals list.


Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2016-06-06 16:59 UTC] cmb@php.net
FWIW, there's <http://lxr.php.net/> which allows for code browsing
of the PHP sources.
 
PHP Copyright © 2001-2017 The PHP Group
All rights reserved.
Last updated: Mon May 29 21:01:36 2017 UTC