[RFC] [Discussion] Doxygen

Hey Jefferson!

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

Do you have Wiki access? You could explain this feature there. Or maybe
send me a write-up directly and I add it. :)

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).

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

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