Re: [RFC] [Vote] Doxygen

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