Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:99522
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.223.172 as permitted sender)
MIME-Version: 1.0
In-Reply-To: <0194b13c-4d68-8e20-b125-6e2f5539e077@fleshgrinder.com>
References: <0194b13c-4d68-8e20-b125-6e2f5539e077@fleshgrinder.com>
Date: Thu, 15 Jun 2017 11:33:16 +0200
Message-ID: <CAF+90c92frB8iBfaiU8f79L-oC9fkr3XppcqJPhjW78jbV6-JQ@mail.gmail.com>
To: Fleshgrinder <php@fleshgrinder.com>
Cc: php-internals <internals@lists.php.net>
Content-Type: multipart/alternative; boundary="001a113effc6c2a90c0551fc5bb7"
Subject: Re: [PHP-DEV] [RFC] [Discussion] Doxygen
From: nikita.ppv@gmail.com (Nikita Popov)

--001a113effc6c2a90c0551fc5bb7
Content-Type: text/plain; charset="UTF-8"

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

--001a113effc6c2a90c0551fc5bb7--