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
signature.asc
Description: OpenPGP digital signature
