Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:99270
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain fleshgrinder.com from 77.244.243.86 cause and error)
References: <e812f2ac-053b-ea6d-0289-4c484ba11916@fleshgrinder.com>
 <5fca5c60-828d-5fb4-8ef8-74d69036e8f8@gmail.com>
To: php-internals <internals@lists.php.net>,
 Stanislav Malyshev <smalyshev@gmail.com>
Message-ID: <5d5fe894-7ef7-23c5-cba1-4cb7a305207f@fleshgrinder.com>
Date: Tue, 30 May 2017 19:53:39 +0200
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:52.0) Gecko/20100101
 Thunderbird/52.1.1
MIME-Version: 1.0
In-Reply-To: <5fca5c60-828d-5fb4-8ef8-74d69036e8f8@gmail.com>
Content-Type: multipart/signed; micalg=pgp-sha256;
 protocol="application/pgp-signature";
 boundary="eFv2JURPo9rVqEiSCHhQvR8F9CMvEWBA4"
Subject: Re: [PHP-DEV] Documentation (Doxygen)
From: php@fleshgrinder.com (Fleshgrinder)

--eFv2JURPo9rVqEiSCHhQvR8F9CMvEWBA4
Content-Type: multipart/mixed; boundary="id417wjjgrgUWnrNdu4XEXUCiH6WuDapi";
 protected-headers="v1"
From: Fleshgrinder <php@fleshgrinder.com>
To: php-internals <internals@lists.php.net>,
 Stanislav Malyshev <smalyshev@gmail.com>
Message-ID: <5d5fe894-7ef7-23c5-cba1-4cb7a305207f@fleshgrinder.com>
Subject: Re: [PHP-DEV] Documentation (Doxygen)
References: <e812f2ac-053b-ea6d-0289-4c484ba11916@fleshgrinder.com>
 <5fca5c60-828d-5fb4-8ef8-74d69036e8f8@gmail.com>
In-Reply-To: <5fca5c60-828d-5fb4-8ef8-74d69036e8f8@gmail.com>

--id417wjjgrgUWnrNdu4XEXUCiH6WuDapi
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: quoted-printable

Hey Stas!

On 5/30/2017 12:50 AM, Stanislav Malyshev wrote:
> Hi!
>=20
>> I used Doxygen in both PRs to document the code. Right now the code ba=
se
>> is lacking a lot of documentation, which, if done right, would greatly=

>> improve accessibility of the code base.
>=20
> Well, the problem as I understand it is that we don't have Doxygen setu=
p
> for docs generation. So, adding docs in Doxygen format is not very
> useful, until we get some Doxygen setup.
>=20
> 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.
>=20
> 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 sys=
tem.
>=20

Not sure if it is really so important to actually generate the doc. It
is imho more important to have documentation in the first place. The
problem with no format is simply that it is not easy to document things
consistently. For instance input/output parameters, return values, where
else to look at, examples, etc.

I am documentation all of my PHP code, everywhere, but never generate
any API docs for it. Just having the documentation as part of the code
is sufficient in 99% of all cases. A simple [Ctrl]+[Q] or hovering with
the mouse will bring it up, that's what I care about. ;)

On 5/30/2017 12:50 AM, Stanislav Malyshev wrote:
> But randomly introducing docs system without any explicit decision in a=
n
> unrelated patch doesn't look like a good idea to me.
>=20

Wow! This sounds like you think that I am trying to deliberately
sabotaging the PHP project. Quite the opposite is the case. I am simply
used to properly documenting my code, as it is part of any professional
code base in my opinion.

--=20
Richard "Fleshgrinder" Fussenegger


--id417wjjgrgUWnrNdu4XEXUCiH6WuDapi--

--eFv2JURPo9rVqEiSCHhQvR8F9CMvEWBA4
Content-Type: application/pgp-signature; name="signature.asc"
Content-Description: OpenPGP digital signature
Content-Disposition: attachment; filename="signature.asc"

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQIbBAEBCAAGBQJZLbGjAAoJEOKkKcqFPVVrPFMP8weAxxcAu3sYFgX40W+E68fu
/HezR6mJlRT+XY+wWex5EkCujGmb371bHpbBqf3aQnQXnKsjnlw8/b/RpELJf6tD
fTtBWkBgubTd1pk1dnEZ9t9ZwzY3KQALMEnkF9y11pqcJu4zuzi4umM/rKSn6maQ
UIEhX0HzbbPH/zXU8SPUBIaWhi1ZxxZZb9bS8Zho94Wx/t7W45zJRKEz4bIXG4Vy
tU8z4WpiT8JH9kmx4tUHh2nxmFtb+UjKoHR1lVWpzX2Oy89eU0bejbGK6Z5d8byk
t/fTVCKfDBAzeSgMiry15L+w1jAN5y5QuS7qSeRvV9fnEJRDinrn/StMVuQhFxWs
gYKme5ZQIpqMTAKEcMIcJCPQkvEtZuIY5RFSii8Ox/lvp9T2Fve0SN5aVrFH12y3
S/HGE5ss9SzZ19skdzWQQNwBJgWS6ctruZR2v0wa1UaqPC+JwHjkEPPnbSOtrp5z
ILlTorfZpFQBlJOBO5DCx8QaUmf+F0p3llbvqWOiKqHW/9H5V0R7T1Ai8N3SiEk8
cXOoHtsrZyeaszBms4x0/wsJEOjGZtnu9LLRr3fUHpnvgfMfSfPv1hirzUxR+lXq
zaWjJMQStgLsUXXyKgk/NuvcGZk77gjlbEowWgHwD8ZwHGJ6zmS+mtC55IugRQSd
5AsVSY4apoO/d38w/1o=
=LNfn
-----END PGP SIGNATURE-----

--eFv2JURPo9rVqEiSCHhQvR8F9CMvEWBA4--