Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:99277
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain fleshgrinder.com from 77.244.243.85 cause and error)
References: <e812f2ac-053b-ea6d-0289-4c484ba11916@fleshgrinder.com>
 <2285c219-41be-a66d-00e2-2e80e4ebe2cd@gmail.com>
To: php-internals <internals@lists.php.net>, jgmdev@gmail.com
Message-ID: <2b291ce0-7213-df38-a7ef-543a6ff14958@fleshgrinder.com>
Date: Tue, 30 May 2017 20:48:32 +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: <2285c219-41be-a66d-00e2-2e80e4ebe2cd@gmail.com>
Content-Type: multipart/signed; micalg=pgp-sha256;
 protocol="application/pgp-signature";
 boundary="jXrTL2vaUChg6pWJII0aRbGuV1UrkXmXd"
Subject: Re: [PHP-DEV] Re: Documentation (Doxygen)
From: php@fleshgrinder.com (Fleshgrinder)

--jXrTL2vaUChg6pWJII0aRbGuV1UrkXmXd
Content-Type: multipart/mixed; boundary="JVila4coGGRtKVb5r7Haj3MgfxvaVP0Ef";
 protected-headers="v1"
From: Fleshgrinder <php@fleshgrinder.com>
To: php-internals <internals@lists.php.net>, jgmdev@gmail.com
Message-ID: <2b291ce0-7213-df38-a7ef-543a6ff14958@fleshgrinder.com>
Subject: Re: [PHP-DEV] Re: Documentation (Doxygen)
References: <e812f2ac-053b-ea6d-0289-4c484ba11916@fleshgrinder.com>
 <2285c219-41be-a66d-00e2-2e80e4ebe2cd@gmail.com>
In-Reply-To: <2285c219-41be-a66d-00e2-2e80e4ebe2cd@gmail.com>

--JVila4coGGRtKVb5r7Haj3MgfxvaVP0Ef
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: quoted-printable

Hey Jefferson!

On 5/30/2017 2:04 AM, Jefferson Gonzalez wrote:
> Hi,
>=20
> It seems that five years ago I was chatting on the php.internals irc an=
d
> I was asking wether documenting the source code with doxygen was
> something that it could be worked on, but it seems that most core
> developers where against having lots of code comments on the engine
> code. So I suggested the idea of taking out the include files and
> prepare them as interface files that could be documented separately. On=
e
> of the core contributors, (which I don't remember right now) said that
> if done well they could accept it.
>=20
> The idea was to add another directory on the source tree of php named
> 'interface' this directory would have three subdirectories: Zend, TSRM
> and main which at the same time would contain stripped down copies of
> the include files with only the declarations of functions, constants,
> typedef, etc... so that they could be documented freely using doxygen
> flavored comments. Ofcourse, this interface files would need to be
> manually maintained, but the result would be documentation that anybody=

> can read to understand the core better and contribute to it.
>=20
> I started a repo (five years ago X_X) https://github.com/jgmdev/phoxyge=
n
> to try and document the php source code with doxygen and put a simple
> Doxyfile that would generate documentation, unfortunately I lost the
> time/motivation due to my day/night job.
>=20
> An inspiration was the wxWidgets project which is doing the same to
> document the project without filling the main codebase with lots of
> comments. You can take a look here:
> https://github.com/wxWidgets/wxWidgets/tree/master/interface, also chec=
k
> the output documentation generated with doxygen:
> http://docs.wxwidgets.org/3.0/
>=20
> In any case when I was coding the php wxWidgets wrapper (wxPHP) I
> struggled a lot to understand the php core while trying to put up a 1:1=

> wrapper of wxWidgets that contains hundreds of classes, and I needed
> good core documentation since I didn't have lots of time to fully read
> and understand the whole PHP core source code.
>=20
> So IMHO an initiative of documenting the core this way has its merits.
>=20

Nice to see that I'm not the only who thinks that proper documentation
is a good thing. I already mentioned that it is not super important to
me personally to actually generate the docs from the code base. However,
there is also nothing bad about doing so. Outsiders or especially PHP
users might be very interested in us doing so.

That being said, what exactly are the arguments for that interface
directory? Why not simply keep the code as is and document it. Saying
that proper documentation is code pollution is like saying every
successful PHP project is crap, because they are properly documented (or
Java, or Rust, or Boost, or C#, or ...).

--=20
Richard "Fleshgrinder" Fussenegger


--JVila4coGGRtKVb5r7Haj3MgfxvaVP0Ef--

--jXrTL2vaUChg6pWJII0aRbGuV1UrkXmXd
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

iQIcBAEBCAAGBQJZLb6BAAoJEOKkKcqFPVVrkJAP/2arRhvoqCFTugtwimGqqUJi
Nsh+0Yyi6dZ9UocF3do7+oRvMrzGGa0PHNLLQTJyxDJp2zEDbrx4vYCKoN3Y8c9U
wwcQAvWMJNmm0i0tFQBDxzquefuT6y3wQ0R/hkVYhGluZw+6tj3b0aiVrO0RkS8u
BRRxlINiI4jcdvomfL+jM3GKOCGkJ1QL+c12PO8gYAJ+HGRKc2rqlpqk65Bjcud4
ky6W3KfqDW8U++Csr3sVU8+qEJC0XypG+Ld+XSow2RxVaLPOr3jHlr0DPFroo7WP
oLqOWmFPtleDYkOWtpZdJoVcgKRcpph2zY+OvcsD/Fii9tHhSc/8MHpyX+iou+Yu
p/Ow0VX263ANGEEI3DZUm99cOIOiXitvI2Cn5jnOOwSf23zORkLQv8BeeoYGA/DE
vSATWFJbijLYKAUQEHHTCnqQ/hjoUGkjGzx0xSeFAObkQPuVM+LmcJDte13psF1/
vhLHuRfRMa6ndBwUKF+fBRC6goII2pshzsXAoLnUkgcylolCjDxFCNaMxmH/+DUZ
mpa0Mt9sWQ/9U/4APgjHca6/06gRCCTQTFZzFpzg/sXVp5AmKA4tpfcl7ZMEwVJ3
QQ14Joa10ZpcOBn11f6heUbqXlM2kv2J5sa3FG/7ij62pE7Ihe/VuM7a+kzNQ9Qu
GYcfvAs1htthYPYav2oi
=3lhf
-----END PGP SIGNATURE-----

--jXrTL2vaUChg6pWJII0aRbGuV1UrkXmXd--