Newsgroups: php.internals Path: news.php.net Xref: news.php.net php.internals:99524 Return-Path: Mailing-List: contact internals-help@lists.php.net; run by ezmlm Delivered-To: mailing list internals@lists.php.net Received: (qmail 24712 invoked from network); 15 Jun 2017 09:54:36 -0000 Received: from unknown (HELO lists.php.net) (127.0.0.1) by localhost with SMTP; 15 Jun 2017 09:54:36 -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 77.244.243.89 cause and error) X-PHP-List-Original-Sender: php@fleshgrinder.com X-Host-Fingerprint: 77.244.243.89 mx108.easyname.com Received: from [77.244.243.89] ([77.244.243.89:54171] helo=mx108.easyname.com) by pb1.pair.com (ecelerity 2.1.1.9-wez r(12769M)) with ESMTP id E1/E5-49155-B5952495 for ; Thu, 15 Jun 2017 05:54:35 -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.84_2) (envelope-from ) id 1dLRTy-0000VP-JK; Thu, 15 Jun 2017 09:54:32 +0000 References: <0194b13c-4d68-8e20-b125-6e2f5539e077@fleshgrinder.com> To: php-internals , Nikita Popov Cc: jgmdev@gmail.com Message-ID: <0f029f49-ee74-efa9-33e2-e26be7dd3e1b@fleshgrinder.com> Date: Thu, 15 Jun 2017 11:54:22 +0200 User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.1.1 MIME-Version: 1.0 In-Reply-To: Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="G23RjHbSTvlXx3su9csFs1GHrXvKQOTUS" X-DNSBL-PBLSPAMHAUS: YES Subject: Re: [PHP-DEV] [RFC] [Discussion] Doxygen From: php@fleshgrinder.com (Fleshgrinder) --G23RjHbSTvlXx3su9csFs1GHrXvKQOTUS Content-Type: multipart/mixed; boundary="ouqh7L9k3tDh8N2egngckcEbKURQbSFud"; protected-headers="v1" From: Fleshgrinder To: php-internals , Nikita Popov Cc: jgmdev@gmail.com Message-ID: <0f029f49-ee74-efa9-33e2-e26be7dd3e1b@fleshgrinder.com> Subject: Re: [PHP-DEV] [RFC] [Discussion] Doxygen References: <0194b13c-4d68-8e20-b125-6e2f5539e077@fleshgrinder.com> In-Reply-To: --ouqh7L9k3tDh8N2egngckcEbKURQbSFud Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: quoted-printable On 6/15/2017 11:33 AM, Nikita Popov wrote: > Hi, >=20 > What makes me skeptical about this is the PR that started this discussi= on: > https://github.com/php/php-src/pull/2523/files >=20 > Documentation sounds nice, but that is not the kind of documentation I > would like to see or find particularly useful. A useful way to document= the > arginfo structure is to write some free-form explanation with an overal= l > example, and then describe the individual macros with one sentence each= =2E > What we get instead is a 30 line doc comment for each macro, describing= it > individually and repeating lots of information that is, of course, the = same > for all arginfo macros. >=20 > Done consequently, what we end up with is ~400 lines of documentation o= f > arginfo macros, documenting everything meticulously, but very redundant= ly > and not particularly usefully. To the contrary, it is noisy and require= s > additional maintenance if anything ever changes or is added. >=20 > Nikita >=20 Hi! It is possible to group things and document them once with Doxygen. A feature Jefferson has pointed out (I was not aware of it). This is something that could be used to document variations of macros that are essentially doing the same (as in the PR you linked). Of course, parameter documentation becomes useless at that point, but it can be challenged if it is useful in the first place if the parameter name is chosen in a way that it explains itself sufficiently. But please note that the RFC is not about the "how to document", this is something that should be part of code reviews. It is about allowing it in the first place and agreeing on a standard way of doing it, that ultimately allows us to generate API documentation (future scope, not part of this RFC). --=20 Richard "Fleshgrinder" Fussenegger --ouqh7L9k3tDh8N2egngckcEbKURQbSFud-- --G23RjHbSTvlXx3su9csFs1GHrXvKQOTUS 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 iQIcBAEBCAAGBQJZQllUAAoJEOKkKcqFPVVrjl0P/0Iqg1TaK+ETjjJRo3saAYxw s1DOQ8att3VTYhsFDUuS01flIaRkhiXPXCOkBBNwUuHaEZqAXFQKN0jQB+mgxoGY WUrZX3RfKkIcC65AA3Nb2QCJQBauFyToOqIgh5xZhx5SpfgHk9+NMh9vjpjFkU/f BsgR24NibZs0g71enxqnaM0NIqVWLuxRAGxEtQ27TasvDiyLbD6p78p/v4ZFJ7KE Dr05BhGjCDYCJvr6EufzXdRAS1kvQZQbWzl5LQJKr3t2uee9l1jmQZxJ2qL+rgY5 LuWaetXTUIbCuUtqMfgtQpQqFaia03yvglfRzlpoh1b2a5u9brTXcUVsdXxFjEM8 RReNheFUkYNPR9FWf+Pz+x6awoWPk8D0VoQROj/EHWuRAv6vdtH6z7q60W7u8oGu +gC+pyae6WtnsI6HGZkpx7NakiB0UAI4JrnaFa9U4zeqSLtbeuATpgMBIm5tvgRd Vggv6Hz/9UwAmpASm/vgF5mpslLPXn4IS3vuXZBAGMTFr2Rk+Ltk1eQb+bZ7xmu1 pXLYPjSivLQ81uXe0Nkin36DsJ6zxHFGbm1fF6Xqfu7VDD30NO0V9BLqb8j1KFwW rXhOCL4bHe6LlcL4VfX0Uy4QUBzM0aoFBT/Bi3P1P+Yvmv0CB/E7GxVQT2YCZ0hR zGBIjZ84RZyMpkTF585/ =HEn/ -----END PGP SIGNATURE----- --G23RjHbSTvlXx3su9csFs1GHrXvKQOTUS--