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.
--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
