On 26/6/17 4:43 pm, Joe Watkins wrote:
Morning,
I also voted no for similar reasons to Anatol.
This is not really a thing that needs a vote, this is a thing that requires
the handful of people who are actually able to document ZE to spend
considerable time doing so. In addition it requires a commitment from the
community of developers to continue to maintain, and introduce inline
documentation with new code.
Additionally, I'm a little concerned that an RFC that has the potential to
touch every single source file has gone to vote with a simple majority. It
would seem that we are deciding that new code must be documented in this
specific way, to say nothing of the massive task of documenting existing
code. That would seem to be a decision that could effect everybody that
works on PHP in perpetuity and a simple majority is nothing like a strong
enough consensus.
Cheers
Joe
I agree that although the intention is good, the burden on developers is likely
to cause it to be unsuccessful. The current state of inline documentation is
partly the result of the culture of PHP, but also the general reluctance of
developers to create documentation :(
Chris
On Sat, Jun 24, 2017 at 10:59 PM, Anatol Belski <weltl...@outlook.de> wrote:
-----Original Message-----
From: Fleshgrinder [mailto:p...@fleshgrinder.com]
Sent: Saturday, June 24, 2017 11:34 PM
To: php-internals <internals@lists.php.net>; Anatol Belski
<weltl...@outlook.de>
Subject: Re: [PHP-DEV] [RFC] [Vote] Doxygen
On 6/24/2017 11:28 PM, Anatol Belski wrote:
I voted no, because it is too short term and I'd see a productivity
drop having such an obligation suddenly right in place for 7.2. To
implement the change, there's more than just to put the doc into the
source. Every piece of code needs to be revisited by someone who
understands it.
I'm not saying the current situation is better than the aim, but to be
realistic - the change needs a culture to be developed. It is clear,
that some know doxygen, but I believe maintaining the doc will be
still a huge effort for many contributors. If some patch were in place
- at least one would have a source for learning by watching, so it
would reduce the learn hurdle 😊 Without being familiar with Doxygen
the actual productivity will for sure suffer.
Neither there's a patch covering at least the very core, nor there's a
strategy for the transition period. I can imagine, that even if the
RFC is voted positive, many contributors not familiar with doxygen
won't have time to complete the doc part. The intention good, but the
assertion might be hard. I might be wrong, but ATM I think the
intention is good, whereby the RFC implementation owes IMHO some
elaborated strategy.
Regards
Anatol
We are only voting that we want to use Doxygen for documentation as a
format, not that documentation is a must for PRs or anything. From the
RFC:
This RFC does not propose any big documentation fest where development
is halted and everybody starts writing documentation. Rather to start
documenting in the future, as well as while refactoring or rewriting
existing code.
Hence, it would be nice to write a little while one is working on
something
anyways.
There is no must to document!
Ok, that was my very concern. Documenting the existing code would also
need profound reviews.
There is a must that IF you document, that it must use Doxygen.
That's what we are voting on. Everybody has plenty of time to get
acquainted
with Doxygen and we can create follow-up RFCs with clearer rules on how
to
document (if need be).
I'd still see an issue, the formulation is a bit slack. If I don't have
to, probably I'd spare 10 minutes I'd have to spend, because a bug
investigation or implementation would take a triple time or more. Depending
on what it takes for me personally in the sum, it could be at least 1 hour
a week, most even 8 hours in a week, that's huge. I'd still say, it needs a
strategy and the community says it's a must. Otherwise, the doc might come
not from a person who implements or understands it. Or - the doc would only
reflect function signatures, which are anyway browsable with lxr, by grep
directly, or the code can be studied from the source.
Thanks
Anatol
--
http://twitter.com/ghrd
--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
