On Thu, Jun 1, 2017 at 9:04 PM, Fleshgrinder <p...@fleshgrinder.com> wrote:
> Hey guys! > > Just finished the very brief Doxygen RFC. Please let me know if you > require more information in it, I feel that it is sufficient as is, > since documenting is not rocket science (writing useful documentation > definitely is, but we cannot vote on that): > > https://wiki.php.net/rfc/doxygen > Hi, What makes me skeptical about this is the PR that started this discussion: https://github.com/php/php-src/pull/2523/files 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 overall example, and then describe the individual macros with one sentence each. 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. Done consequently, what we end up with is ~400 lines of documentation of arginfo macros, documenting everything meticulously, but very redundantly and not particularly usefully. To the contrary, it is noisy and requires additional maintenance if anything ever changes or is added. Nikita
