Everything

php

Documentation (Doxygen)

php.internals

Fleshgrinder

9 years ago

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.

--
Richard "Fleshgrinder" Fussenegger

Fleshgrinder

9 years ago

On 5/24/2017 12:33 PM, 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.
>

Bump, would be great to get some feedback here. :)

--
Richard "Fleshgrinder" Fussenegger

Stas Malyshev

9 years ago

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

Fleshgrinder

9 years ago

Hey Stas!

On 5/30/2017 12:50 AM, Stanislav Malyshev wrote:

> 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.
>

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 an
> unrelated patch doesn't look like a good idea to me.
>

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.

--
Richard "Fleshgrinder" Fussenegger

Stas Malyshev

9 years ago

Hi!

>> But randomly introducing docs system without any explicit decision in an
>> unrelated patch doesn't look like a good idea to me.
>>
>
> 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

Sorry if it sounded that way, I of course meant nothing like it. I just
meant that introducing docs standard should not be made in a routine
unrelated patch, where it could be missed by many people, but as an
ordered process. Otherwise, you'd introduce Doxygen, somebody unaware of
it would introduce another thing, and pretty soon we have code
documented in a dozen of incompatible ways and it's a mess. I certainly
did not imply any malice on your part, just that we need to do it in an
explicit way that informs everybody what it happening.

> used to properly documenting my code, as it is part of any professional
> code base in my opinion.

Surely, and it's without doubt a good thing. We just need to do it
right, otherwise we'd have to spend more time later to fix it. It
requires a bit of time, but better spend it now than end up with code
documented in a way that no doc system would be able to parse, IMO.

--
Stas Malyshev
smalyshev@gmail.com

Fleshgrinder

9 years ago

On 5/30/2017 9:26 PM, Stanislav Malyshev wrote:

> Hi!
>
> Sorry if it sounded that way, I of course meant nothing like it. I just
> meant that introducing docs standard should not be made in a routine
> unrelated patch, where it could be missed by many people, but as an
> ordered process. Otherwise, you'd introduce Doxygen, somebody unaware of
> it would introduce another thing, and pretty soon we have code
> documented in a dozen of incompatible ways and it's a mess. I certainly
> did not imply any malice on your part, just that we need to do it in an
> explicit way that informs everybody what it happening.
>
>> used to properly documenting my code, as it is part of any professional
>> code base in my opinion.
>
> Surely, and it's without doubt a good thing. We just need to do it
> right, otherwise we'd have to spend more time later to fix it. It
> requires a bit of time, but better spend it now than end up with code
> documented in a way that no doc system would be able to parse, IMO.
>

No offense taken. :) I totally agree with you in all of this. Writing an
RFC for every tiny thing is a lot of work, but it is the correct way of
doing things, so I'll sit down and do exactly that.

--
Richard "Fleshgrinder" Fussenegger

Jefferson Gonzalez

9 years ago

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:

Fleshgrinder

9 years ago

Hey Jefferson!

On 5/30/2017 2:04 AM, Jefferson Gonzalez wrote:

> 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.
>

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 ...).

--
Richard "Fleshgrinder" Fussenegger

Jefferson Gonzalez

9 years ago

On 05/30/2017 02:48 PM, Fleshgrinder wrote:

> 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.

Basically the advantage of generating documentation from the codebase is
that it could help attract more people to contribute into the core. Also
it would ease the introductory barrier for those that want to extend PHP
with modules.

>
> 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 ...).

I do not remember all the details, since this was 5 years ago as I wrote
before, but what I do remember is some of the core developers not
wanting to saturate the core code with comments, and that the best
documentation was reading the actual source. This is why I suggested the
idea of creating an additional directory named interface with a mirror
of definitions and declarations found in actual include files that could
be freely documented until heart is content. And this has worked
beautifully for the wxWidgets project.

lists@rhsoft.net

9 years ago

Am 05.06.2017 um 20:16 schrieb Jefferson Gonzalez:

> I do not remember all the details, since this was 5 years ago as I wrote
> before, but what I do remember is some of the core developers not
> wanting to saturate the core code with comments, and that the best
> documentation was reading the actual source

please wash me but do not make me wet...