# Documentation (Doxygen) - Thread: https://externals.io/message/99140 - Original archive: https://news-web.php.net/php.internals/99140 - Started by Fleshgrinder on 2017-05-24T10:33:33+00:00 - Messages: 10 - RFC: Doxygen (Declined) — https://externals.io/rfc/doxygen.md - Reply by email to internals@lists.php.net - More for agents: search with https://externals.io/search.md?q={query} · RFCs at https://externals.io/rfc.md · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt --- ## #99140 — Fleshgrinder — 2017-05-24T10:33:33+00:00 URL: https://externals.io/message/99140#99140 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 --- ## #99242 — Fleshgrinder — 2017-05-29T22:14:24+00:00 URL: https://externals.io/message/99140#99242 · In reply to: #99140 > 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 --- ## #99243 — Stanislav Malyshev — 2017-05-29T22:50:52+00:00 URL: https://externals.io/message/99140#99243 · In reply to: #99140 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 --- ## #99245 — Jefferson Gonzalez — 2017-05-30T00:04:34+00:00 URL: https://externals.io/message/99140#99245 · In reply to: #99140 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. > 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. --- ## #99270 — Fleshgrinder — 2017-05-30T17:53:39+00:00 URL: https://externals.io/message/99140#99270 · In reply to: #99243 Hey Stas! > Hi! > > > […] > > 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 --- ## #99277 — Fleshgrinder — 2017-05-30T18:48:32+00:00 URL: https://externals.io/message/99140#99277 · In reply to: #99245 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 --- ## #99280 — Stanislav Malyshev — 2017-05-30T19:26:59+00:00 URL: https://externals.io/message/99140#99280 · In reply to: #99270 Hi! > > […] > > 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 --- ## #99281 — Fleshgrinder — 2017-05-30T19:32:20+00:00 URL: https://externals.io/message/99140#99281 · In reply to: #99280 > 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. > > > […] > > 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 --- ## #99370 — Jefferson Gonzalez — 2017-06-05T18:16:58+00:00 URL: https://externals.io/message/99140#99370 · In reply to: #99277 > 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. --- ## #99371 — lists@rhsoft.net — 2017-06-05T18:24:40+00:00 URL: https://externals.io/message/99140#99371 · In reply to: #99370 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...