search

php / php-src

The PHP Interpreter
https://www.php.net
Other
38.29k stars 7.76k forks source link

Expand/improve docs (https://php.github.io/php-src/) #15954

Open DanielEScherzer opened 2 months ago

DanielEScherzer commented 2 months ago

Description

Having recently started contributing to PHP, I have found that I frequently needed to look through a bunch of different source files to figure out how different macros/types/patterns are used. I propose expanding https://php.github.io/php-src/ to better document these, to make things easier for new (and hopefully also existing?) contributors.

I'm happy to work on writing the documentation if it would be accepted, and some initial points that I suggest documenting are

And there are probably a whole bunch of other areas that I just haven't run into

iluuu1994 commented 2 months ago

In case you haven't seen it, there are quite a few resources listed in the CONTRIBUTING guide: https://github.com/php/php-src/blob/master/CONTRIBUTING.md#technical-resources

Nonetheless, expanding the documentation is always appreciated! I don't think the documentation should become an exhaustive reference, but it absolutely makes sense to explain each programming concept so that developers can learn to look up and understand the code easier.

DanielEScherzer commented 2 months ago

I found https://www.phpinternalsbook.com/ really helpful, and understand it doesn't need to be exhaustive, but since https://php.github.io/php-src/ says that the documentation is a work in progress, I assumed it would be helpful to do some of that work

iluuu1994 commented 2 months ago

@DanielEScherzer Absolutely. I was just trying to clarify this beforehand, to avoid wasting your time. But yes, we absolutely would appreciate work on documentation. Newcomers are actually perfect candidates, because they have a much better notion of what is obvious/intuitive and what isn't.