Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:99370
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.217.178 as permitted sender)
To: Fleshgrinder <php@fleshgrinder.com>,
 php-internals <internals@lists.php.net>
References: <e812f2ac-053b-ea6d-0289-4c484ba11916@fleshgrinder.com>
 <2285c219-41be-a66d-00e2-2e80e4ebe2cd@gmail.com>
 <2b291ce0-7213-df38-a7ef-543a6ff14958@fleshgrinder.com>
Message-ID: <b6c7383c-7bfa-2edd-e722-526bbbe62c30@gmail.com>
Date: Mon, 5 Jun 2017 14:16:58 -0400
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101
 Thunderbird/52.1.1
MIME-Version: 1.0
In-Reply-To: <2b291ce0-7213-df38-a7ef-543a6ff14958@fleshgrinder.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] Re: Documentation (Doxygen)
From: jgmdev@gmail.com (Jefferson Gonzalez)

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.