Newsgroups: php.internals Path: news.php.net Xref: news.php.net php.internals:99633 Return-Path: Mailing-List: contact internals-help@lists.php.net; run by ezmlm Delivered-To: mailing list internals@lists.php.net Received: (qmail 81924 invoked from network); 24 Jun 2017 21:34:52 -0000 Received: from unknown (HELO lists.php.net) (127.0.0.1) by localhost with SMTP; 24 Jun 2017 21:34:52 -0000 Authentication-Results: pb1.pair.com smtp.mail=php@fleshgrinder.com; spf=permerror; sender-id=unknown Authentication-Results: pb1.pair.com header.from=php@fleshgrinder.com; sender-id=unknown Received-SPF: error (pb1.pair.com: domain fleshgrinder.com from 212.232.25.164 cause and error) X-PHP-List-Original-Sender: php@fleshgrinder.com X-Host-Fingerprint: 212.232.25.164 mx208.easyname.com Received: from [212.232.25.164] ([212.232.25.164:52786] helo=mx208.easyname.com) by pb1.pair.com (ecelerity 2.1.1.9-wez r(12769M)) with ESMTP id E1/48-12245-AFADE495 for ; Sat, 24 Jun 2017 17:34:50 -0400 Received: from cable-81-173-132-37.netcologne.de ([81.173.132.37] helo=[192.168.178.20]) by mx.easyname.com with esmtpsa (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.89) (envelope-from ) id 1dOshX-0008Vo-Px; Sat, 24 Jun 2017 21:34:45 +0000 References: <31e715a7-d129-17f0-b870-52bc1ca1715d@fleshgrinder.com> <76397c50-1bb6-a777-2f72-25a7ed9981dc@fleshgrinder.com> To: php-internals , Anatol Belski Message-ID: <4f803b88-813d-dacb-db05-248b5e372899@fleshgrinder.com> Date: Sat, 24 Jun 2017 23:34:20 +0200 User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.2.1 MIME-Version: 1.0 In-Reply-To: Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="aRD5DH8mhegxAHeP6NUlUBxbQ3bKRDUrc" X-DNSBL-PBLSPAMHAUS: YES Subject: Re: [PHP-DEV] [RFC] [Vote] Doxygen From: php@fleshgrinder.com (Fleshgrinder) --aRD5DH8mhegxAHeP6NUlUBxbQ3bKRDUrc Content-Type: multipart/mixed; boundary="IS9NqDljmarGObx98BNo9N0nLumhbsqRX"; protected-headers="v1" From: Fleshgrinder To: php-internals , Anatol Belski Message-ID: <4f803b88-813d-dacb-db05-248b5e372899@fleshgrinder.com> Subject: Re: [PHP-DEV] [RFC] [Vote] Doxygen References: <31e715a7-d129-17f0-b870-52bc1ca1715d@fleshgrinder.com> <76397c50-1bb6-a777-2f72-25a7ed9981dc@fleshgrinder.com> In-Reply-To: --IS9NqDljmarGObx98BNo9N0nLumhbsqRX Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: quoted-printable 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. >=20 > 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 =F0=9F=98=8A Without being familiar wi= th > Doxygen the actual productivity will for sure suffer. >=20 > 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. >=20 > Regards >=20 > Anatol >=20 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 RF= C: > 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! 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). --=20 Richard "Fleshgrinder" Fussenegger --IS9NqDljmarGObx98BNo9N0nLumhbsqRX-- --aRD5DH8mhegxAHeP6NUlUBxbQ3bKRDUrc Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQIcBAEBCAAGBQJZTtryAAoJEOKkKcqFPVVrDsgP/15pGSX48uXHg1tMX0ls7Wst RE3O7XvJK/+eVrMIPbZDtMWLzx966z06KW9dbzHVGYk6AbbCN8tvfLgST60s7LL3 idPwBq359wXjuOogp6ARKiYfTaxP5zVbEZ0kVHs3bocW3COPGI3/FepgKUdKBsGP ej01Skj2XpzWHOVtL15P01FKlSWPAK7OaVTeLMB5X7vP4TCWJvjeo67tioELDghI 4zoCAVVRGzm2neutlgA8J5VoaVbRvaZUrb1n8nJr+sivxp0ODBFSyqr9hjm4wrbE 2kG70D6KEU0Yjpk8x4iGjdeTAosmLPe9hT2Hx6VCbXUq3kkEWCaTkWrrqA7SWU3B OI7mHSodG5v/GrDOLztQqrAywP4A/LGeLI1AayyylbT3HocyF3WYD0ite7zWRJaM /4spqjtxzP6QW1fj/HFmiynphsXL2lRJNjwm7CLtb3ZnSUY75xLDizJXJQPyisIt fC8lCs8rMHryrQrVLxLS+tMckhAmYEfgAdbrDOwlYQJ1qRYfufGIC0oVYH3che5A ocWZktld6aazL3QC3gLp+UAiqS3ksGowLUG6kUaZM+NVsaaeq/BMLUfpSa6pH/wh BFdi4YUVAGp5/pvE389xchHucfUkEL312NkO++n3uI4hX6XPw1MxhacDzgCo2e+0 GJxWyC2yJtdbrp+vVmTr =jEL8 -----END PGP SIGNATURE----- --aRD5DH8mhegxAHeP6NUlUBxbQ3bKRDUrc--