On 07/05/2021 09:10, Nikita Popov wrote:
If we want to include "writing documentation"
as part of the change process, then it would be much more valuable to write
documentation for php.net, which is used by hundreds of thousands of
developers, rather than the language specification, which is used by a
handful at best.
I agree with this.
The reality is, the specification is just another form of documentation.
When it was written, there was a realistic prospect of two competing
implementations needing to agree on new features, but that never
happened, so if the spec doesn't agree with the implementation, it's
always the spec that's wrong.
If we want the behaviour of the language to be better documented, we
have existing places for that:
* Incorporate formal descriptions from the language spec into the
manual. Maybe we need a way of embedding grammar snippets into
appropriate chapters.
* Document behaviour in edge cases - defaults, error conditions,
interactions of options, etc. You don't have to be writing an
implementation to want to know that stuff.
* Encourage, or require, contributors to write some basic documentation
of new features. We have bundled functions and options without even a
single sentence in the manual.
* Write tests, and label them clearly. If anyone wants to write an
alternative implementation, they can run the test suite against it.
Regards,
--
Rowan Tommins
[IMSoP]
--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: https://www.php.net/unsub.php
