Document stubs #13677
Document stubs #13677
Conversation
kocsismate
added
the
Category: Documentation
kocsismate
force-pushed
the
stub-docs
branch
3 times, most recently
from
c6c16d2
to
90b2a67
Compare
There was a problem hiding this comment.
Thank you! I did read this in detail. There are some grammatical oddities, but I'm not sure code reviews are a good tool to fix those.
Please check the README on how to auto-format the files.
Thank you for providing some documentation on the frameless calls 🙂
docs/source/miscellaneous/stubs.rst
Outdated
| Stubs | ||
| ################# | ||
|
|
||
| Stub files are pieces of plain PHP code which only contain declarations without actually runnable code. A very basic stub |
There was a problem hiding this comment.
I think you should start out explaining what problem stubs solve exactly, along with maybe a simple example of a stub and a function implementation.
There was a problem hiding this comment.
I'll try to come up with a better intro.. I also felt that the current one is not very good :D
docs/source/miscellaneous/stubs.rst
Outdated
| compile-time. The feature internally works by adding the ``ZEND_ACC_COMPILE_TIME_EVAL`` function flag. | ||
|
|
||
| As of PHP 8.4, the concept of arity-based frameless functions was introduced. This is another optimization technique, | ||
| which results in faster internal function calls by eliminating unnecessary checks for the number of passed parameters |
There was a problem hiding this comment.
Mostly, it is about not creating a stack frame, but passing arguments to the function directly via the ICALL operands. Hence the name "frameless".
Feel free to point these out/suggest a better wording, and I'll try to fix them! I wouldn't want to provide docs which scares native speakers. |
|
I could do quite a bit to make this easier to read — but would it make sense if I spend an hour on it? |
|
@derickr just a gentle ping: will you have capacity on improving the wording in the near future? |
Edit for clarity, add some examples, and use foo/bar less
|
With the help of Derick, the documentation was revamped :) |
|
@iluuu1994 If you have followup suggestions, or anything comes to your mind which should be improved, feel free to reach out to me! |
|
The documentation is now live at https://php.github.io/php-src/miscellaneous/stubs.html |
I'm not a good writer, so feel free to suggest better wording/rephrase the text wherever needed :)