Hi, > -----Original Message----- > From: Fleshgrinder [mailto:p...@fleshgrinder.com] > Sent: Friday, June 23, 2017 9:20 PM > To: php-internals <internals@lists.php.net>; christopher.jo...@oracle.com > Subject: Re: [PHP-DEV] [RFC] [Vote] Doxygen > > On 6/23/2017 5:12 AM, Christopher Jones wrote: > > That kind of detail belongs in the RFC. > > > > A link to existing 'prior art' would have rounded the picture out and > > let people decide between alternatives of internal vs external doc. > > E.g. link to https://wiki.php.net/internals/references > > > > Also, is this for core and for extensions? Or for core only? What > > about PECL extensions not part of the PHP bundle? > > > > In summary, see point 8 of > > https://blogs.oracle.com/opal/the-mysterious-php-rfc-process-and-how-y > > ou-can-change-the-web > > > > > > Chris > > > > Hi Chris! > > I agree and if I would have thought about it, I would have included it. > (This is not an excuse, just the honest truth.) I can create a follow up RFC > with > more detailed rules, or maybe we wait a little so that everybody can get > acquainted with Doxygen first. > > Regarding PECL: I clearly state in the introduction "for the C sources of > PHP" (in > other words, everything inside the php-src repository) and I would stick to > that. > PECL authors should be allowed, like Composer authors, to do whatever they > want. PECL extensions that are to be included in "the C sources of PHP" should > of course adopt the style, like it is already today in regards to the code > style. > Otherwise we can never get to the "future scope" of actually generating docs > for browsing. > 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
