php
Add msgpack (MessagePack) documentation
The PECL msgpack extension (a MessagePack implementation) is not yet documented. This PR aims to change that. Although this PR does not currently include a fully featured documentation, I hope it is a start that we can build on.
Since msgpack is comparable to igbinary, I outsourced some notes to be able to reuse them. In addition, I changed the link in the memcached doc to redirect to this new documentation instead of pecl.php.net.
As a source of this extension, I walked through the source code of msgpack, honestly not quite understanding every single detail of it.
I am looking forward to your comments!
Are you the maintainer of the extension?
I am not really a fan of adding new PECL extension to the php.net website as it gives a lot of burden for doc maintainers (and translations) to fix issues with it.
Especially if the extension does not have stub files that allows for easy syncing/page generation.
Are you the maintainer of the extension?
No, I am not. I think @m6w6 is.
I am not really a fan of adding new PECL extension to the php.net website as it gives a lot of burden for doc maintainers (and translations) to fix issues with it.
That is definitely a fair point, that I think should be stated somewhere in the contribution guidelines. Although I am not sure if that is already your last word in this case.
From my point of view, the msgpack doc closes a gap: msgpack is used by and referenced in memcached and it is an alternative to the pretty similar igbinary with major advantages when it comes to cross-language use cases. Both memcached and igbinary are included in this documentation.
Also, msgpack is the 27th most downloaded extension on pecl.php.net (out of 439) and that is without even being mentioned on php.net. So it is not any random, rarely used extension.
In addition, I could help with the German translation at least.
Especially if the extension does not have stub files that allows for easy syncing/page generation.
I could create a PR to add a stub file as well, if that helps.
Please let me know, if I can help in other ways to bring this to php.net!
Are you the maintainer of the extension?
No, I am not. I think @m6w6 is.
I am not really a fan of adding new PECL extension to the php.net website as it gives a lot of burden for doc maintainers (and translations) to fix issues with it.
That is definitely a fair point, that I think should be stated somewhere in the contribution guidelines. Although I am not sure if that is already your last word in this case.
From my point of view, the msgpack doc closes a gap: msgpack is used by and referenced in memcached and it is an alternative to the pretty similar igbinary with major advantages when it comes to cross-language use cases. Both memcached and igbinary are included in this documentation.
Also, msgpack is the 27th most downloaded extension on pecl.php.net (out of 439) and that is without even being mentioned on php.net. So it is not any random, rarely used extension.
The memcached docs have existed for ages and are not maintained, and until you submitted a PR was missing a function from version 3.1.0 which is dated 2018. This is not really a position I am happy with, documentation is an integral part of any project, and having them "subcontracted" to be dealt by an external, volunteer, person who has no idea how the extension works or needs to figure is bad. Especially as we, the documentation project, get flack when people complain about missing docs.
Personally, I would rather get rid of all PECL docs than add new ones.
And the igbinary extension docs were at least written by the maintainer.
Moreover, the PECL page for the extension points to https://msgpack.org/, so it is documented, just not on php.net and that is fine.
In addition, I could help with the German translation at least.
I appreciate the offer, but my main concern is that this might get stale quickly. Similar to the above.
Especially if the extension does not have stub files that allows for easy syncing/page generation.
I could create a PR to add a stub file as well, if that helps.
That would help, just from the extension maintenance PoV. But again, I am not convinced about integrating the docs. Especially as it is already documented by them externally.
Please let me know, if I can help in other ways to bring this to php.net!
There is the usual bug triage, submitting PRs for issues, or improving PhD (the doc renderer)
Moreover, the PECL page for the extension points to https://msgpack.org/, so it is documented, just not on php.net and that is fine.
Just to note, https://msgpack.org/ is more like a documentation of the protocol than a documentation of the PHP extension with its functions and classes.
I understand your point of view, these are absolutely fair points! Closing this PR