Everything
php
Learn Community Releases The PHP Project
Home » Project » Newsgroups » php.internals » [RFC] [Discussion] Doxygen »

[RFC] [Discussion] Doxygen

php.internals

Fleshgrinder

9 years ago
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
-- Richard "Fleshgrinder" Fussenegger

Jefferson Gonzalez

9 years ago
On 06/01/2017 03:04 PM, Fleshgrinder 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 >
First, thanks for taking the initiative to do this! Second, the rfc doesn't touch the ability of grouping that doxygen provides which could be really useful in order to navigate the documentation more easily. For example: grouping functions related to the manipulation of zvals in groups like: Objects, Strings, Numbers, etc... More about this: http://www.stack.nl/~dimitri/doxygen/manual/grouping.html and this is some example of how it may look like: http://docs.wxwidgets.org/trunk/modules.html Third, maybe you can add 2 vote choices in which to document the source code in case one is favored more than another. One to document the core directly and another method using the interface directory that I mentioned in my previous e-mail. Finally, you mentioned on the RFC that I didn't got any support which could sound harsh... but what I wrote on the e-mail was that I lost motivation due to my day/night job, that was the real reason I did not continued the work with it. Cheers!

Fleshgrinder

9 years ago
Hey Jefferson! On 6/5/2017 8:40 PM, Jefferson Gonzalez wrote:
> First, thanks for taking the initiative to do this! >
:) On 6/5/2017 8:40 PM, Jefferson Gonzalez wrote:
> Second, the rfc doesn't touch the ability of grouping that doxygen > provides which could be really useful in order to navigate the > documentation more easily. For example: grouping functions related to > the manipulation of zvals in groups like: Objects, Strings, Numbers, > etc... More about this: > http://www.stack.nl/~dimitri/doxygen/manual/grouping.html > and this is some example of how it may look like: > http://docs.wxwidgets.org/trunk/modules.html >
Do you have Wiki access? You could explain this feature there. Or maybe send me a write-up directly and I add it. :) On 6/5/2017 8:40 PM, Jefferson Gonzalez wrote:
> Third, maybe you can add 2 vote choices in which to document the source > code in case one is favored more than another. One to document the core > directly and another method using the interface directory that I > mentioned in my previous e-mail. >
The problem I have with this approach is that we have to maintain two header files. One is already total overkill in my book (luckily other languages have learned from this). On 6/5/2017 8:40 PM, Jefferson Gonzalez wrote:
> Finally, you mentioned on the RFC that I didn't got any support which > could sound harsh... but what I wrote on the e-mail was that I lost > motivation due to my day/night job, that was the real reason I did not > continued the work with it. >
I actually wanted it to sound dramatic, but will change it to the real reason. ;)
-- Richard "Fleshgrinder" Fussenegger

Fleshgrinder

9 years ago
On 6/1/2017 9:04 PM, Fleshgrinder 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 >
I would like to start voting on this, unless someone has still an open question regarding this. @Jefferson would you like to extend the RFC before we start the vote?
-- Richard "Fleshgrinder" Fussenegger

Nikita Popov

9 years ago
On Thu, Jun 1, 2017 at 9:04 PM, Fleshgrinder <php@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

Fleshgrinder

9 years ago
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