Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:99245
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.213.48 as permitted sender)
To: php-internals <internals@lists.php.net>
Cc: Nikita Popov <nikita.ppv@gmail.com>
References: <e812f2ac-053b-ea6d-0289-4c484ba11916@fleshgrinder.com>
Message-ID: <2285c219-41be-a66d-00e2-2e80e4ebe2cd@gmail.com>
Date: Mon, 29 May 2017 20:04:34 -0400
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101
 Thunderbird/52.1.1
MIME-Version: 1.0
In-Reply-To: <e812f2ac-053b-ea6d-0289-4c484ba11916@fleshgrinder.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Subject: Re: Documentation (Doxygen)
From: jgmdev@gmail.com (Jefferson Gonzalez)

Hi,

It seems that five years ago I was chatting on the php.internals irc and 
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. One 
of the core contributors, (which I don't remember right now) said that 
if done well they could accept it.

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.

I started a repo (five years ago X_X) https://github.com/jgmdev/phoxygen 
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.

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 check 
the output documentation generated with doxygen: 
http://docs.wxwidgets.org/3.0/

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.

So IMHO an initiative of documenting the core this way has its merits.

On 05/24/2017 06:33 AM, Fleshgrinder wrote:
> Hey internals!
> 
> Nikic recommended that we discuss this topic before my latest PRs can be
> merged.
> 
> https://github.com/php/php-src/pull/2523
> https://github.com/php/php-src/pull/2535
> 
> 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.
> 
> The decision for Doxygen was not really a question of taste or anything,
> it's just one I know very well for C. I am open to anything, as long as
> we do something.
>