Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:99243
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.218.45 as permitted sender)
To: php-internals <internals@lists.php.net>
References: <e812f2ac-053b-ea6d-0289-4c484ba11916@fleshgrinder.com>
Cc: Nikita Popov <nikita.ppv@gmail.com>
Message-ID: <5fca5c60-828d-5fb4-8ef8-74d69036e8f8@gmail.com>
Date: Mon, 29 May 2017 15:50:52 -0700
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.11; rv:45.0)
 Gecko/20100101 Thunderbird/45.8.0
MIME-Version: 1.0
In-Reply-To: <e812f2ac-053b-ea6d-0289-4c484ba11916@fleshgrinder.com>
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] Documentation (Doxygen)
From: smalyshev@gmail.com (Stanislav Malyshev)

Hi!

> I used Doxygen in both PRs to document the code. Right now the code base
> is lacking a lot of documentation, which, if done right, would greatly
> improve accessibility of the code base.

Well, the problem as I understand it is that we don't have Doxygen setup
for docs generation. So, adding docs in Doxygen format is not very
useful, until we get some Doxygen setup.

If we don't get one, then I think it's better to use format that is
either completely generic (no special tags, etc.) or matching existing
usage.

Or make an RFC to establish docs standard, be it Doxygen or anything
else. Which of course would include some plan on how to deploy that system.

But randomly introducing docs system without any explicit decision in an
unrelated patch doesn't look like a good idea to me.
-- 
Stas Malyshev
smalyshev@gmail.com