Newsgroups: php.internals Path: news.php.net Xref: news.php.net php.internals:99593 Return-Path: Mailing-List: contact internals-help@lists.php.net; run by ezmlm Delivered-To: mailing list internals@lists.php.net Received: (qmail 90194 invoked from network); 21 Jun 2017 15:43:58 -0000 Received: from unknown (HELO lists.php.net) (127.0.0.1) by localhost with SMTP; 21 Jun 2017 15:43:58 -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.28.122 cause and error) X-PHP-List-Original-Sender: php@fleshgrinder.com X-Host-Fingerprint: 212.232.28.122 mx201.easyname.com Received: from [212.232.28.122] ([212.232.28.122:55091] helo=mx201.easyname.com) by pb1.pair.com (ecelerity 2.1.1.9-wez r(12769M)) with ESMTP id E1/6D-13828-D349A495 for ; Wed, 21 Jun 2017 11:43:57 -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 1dNhnN-0004Nq-02; Wed, 21 Jun 2017 15:43:54 +0000 References: To: php-internals , Nikita Popov Message-ID: <31e715a7-d129-17f0-b870-52bc1ca1715d@fleshgrinder.com> Date: Wed, 21 Jun 2017 17:43:51 +0200 User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.2.0 MIME-Version: 1.0 In-Reply-To: Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="L9xCwRHREal5bFmj9jA5fwRVuo777E6Xw" X-DNSBL-PBLSPAMHAUS: YES Subject: Re: [PHP-DEV] [RFC] [Vote] Doxygen From: php@fleshgrinder.com (Fleshgrinder) --L9xCwRHREal5bFmj9jA5fwRVuo777E6Xw Content-Type: multipart/mixed; boundary="RKN95jnl8h8koSTOrn1BB4CwNrwV0qgtV"; protected-headers="v1" From: Fleshgrinder To: php-internals , Nikita Popov Message-ID: <31e715a7-d129-17f0-b870-52bc1ca1715d@fleshgrinder.com> Subject: Re: [PHP-DEV] [RFC] [Vote] Doxygen References: In-Reply-To: --RKN95jnl8h8koSTOrn1BB4CwNrwV0qgtV Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: quoted-printable On 6/21/2017 5:38 PM, Nikita Popov wrote: > Can you please clarify where functions that are declared in a header an= d > defined in a source file should be documented? I believe the usual > recommendation is to document in the source file, because it's closer t= o > the implementation and thus more likely to be updated. On the other han= d, > documentation in headers only is more useful if you're just browsing co= de > and not using generated output. >=20 > Nikita >=20 The documentation should go into the header file. Source files actually must not have documentation, because everything in there is private anyways. Unless it is exported via a header file that is. Doxygen will automatically inherit the documentation (no @inheritDoc necessary), because it understands the C code in C mode. Documentation should never document what the implementation does, only how it can be used. This gets blurry if you implement a particular, standardized algorithm (like the UUIDs) where the actual implementation suddenly becomes an important part of information that should go into the documentation. In other words, refactoring and other changes in a functions body should not require changes of the documentation. A usage change usually directly translates to a breaking change. A situation in which many places require updates (e.g. CHANGELOG, NEWS, ...) and not something a dev should do without thinking about the implications of doing so. --=20 Richard "Fleshgrinder" Fussenegger --RKN95jnl8h8koSTOrn1BB4CwNrwV0qgtV-- --L9xCwRHREal5bFmj9jA5fwRVuo777E6Xw 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 iQIcBAEBCAAGBQJZSpQ3AAoJEOKkKcqFPVVrweEP/2SlMeCsCsgtYSeT5mYYiEj2 KzigVyKPwZKI78QZNE3Z6uxNlPOVRDVJE1JJH43Uapna8Ys45F3dxREFWnfTWhbI qqAGdfX7l75q8iSqZvAQYeio1J25ygb/KBJFWRvL85T3hkNMMS1Fx+mYm0zFPKi/ /fDSjU6xy8S3yNzc/DIPFnjF4fYtYcHIaDzDt9ODZeaU1f7rbseLjOeAHv/3lXdm Z3CpE8z1oBEtZ8A6LosJoVgV+6B6j6auu0Uv0VdBH/X/U6CcE340N0ONdN1u22HC 9UvZrEmh6nlrqYLt92pQ0+AFTnyXEYOuob62sOVAhqT2Vx9jCPQN/yOywzE6esTx vClGxtg24OUeBFH44z0xR6LA5fkhfBUiNU//argMghkJhgRGpKuwNzZSp9k39I01 kKI+8ST1StUBhXOWc71cbTqiz5eUs7bkxhLXUN1NRk5OiFYjWfI4Btr4VZxw7nJe rZ6JKvEpJlaCjPHoGtBhIxix5GuHN2g12t26FKH1/o5pBhNePNcs38//a1mAnKRn SaXk1wZIZb0zDY0v0aVpMa8mqUJ5MzDGxVpI95e1ML3UFuNB6J3qsIpwEaLh3xsb png3EBoWVHSH2CRSvxqr9B7sqxvE2+X+8ud6INUXo1zpcZAPf48xUiDXbqV9kVZl QDUObbluM5Dy54HSpXNz =Szg4 -----END PGP SIGNATURE----- --L9xCwRHREal5bFmj9jA5fwRVuo777E6Xw--