On 6/15/2017 11:33 AM, Nikita Popov wrote: > 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 >
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). -- Richard "Fleshgrinder" Fussenegger
signature.asc
Description: OpenPGP digital signature
