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