On 22/6/17 1:43 am, Fleshgrinder wrote:
On 6/21/2017 5:38 PM, Nikita Popov wrote:
Can you please clarify where functions that are declared in a header and
defined in a source file should be documented? I believe the usual
recommendation is to document in the source file, because it's closer to
the implementation and thus more likely to be updated. On the other hand,
documentation in headers only is more useful if you're just browsing code
and not using generated output.
Nikita
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.
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-you-can-change-the-web
Chris
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.
--
http://twitter.com/ghrd
--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
