RE: [PHP-DEV] [RFC] [Vote] Doxygen

> -----Original Message----- > From: Fleshgrinder [mailto:php@fleshgrinder.com] > Sent: Saturday, June 24, 2017 11:34 PM > To: php-internals <internals@lists.php.net>; Anatol Belski > <weltling@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