Documentation (Doxygen)

Hey Stas!

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

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

Hey Jefferson!

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