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

[DanielEScherzer]

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

• parameter parsing and function declaration (lots of zend_API.h stuff)
• the compatibility macros/debug tools/compiler hints (zend_portability.h)
• data structures other than zval and zend_string, like class entries, properties, constants, and methods (zend_compile.h)
• globals and the interaction with thread safety (zend_globals.h, zend_globals_macros.h)
• arrays/HashTable (zend_types.h, zend_hash.h)

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

[iluuu1994]

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]

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]

@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.