Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:99648
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain oracle.com from 156.151.31.81 cause and error)
To: internals@lists.php.net
References: <e982c2fa-e08c-0970-53d2-c0d6421c9573@fleshgrinder.com>
 <CAF+90c-9uSA+ykCWg_+pSRdZpJcLoScHawK8MWVGGjCx+dA59g@mail.gmail.com>
 <31e715a7-d129-17f0-b870-52bc1ca1715d@fleshgrinder.com>
 <af8671d1-9040-39ca-6a8b-fe589d94e2b5@oracle.com>
 <76397c50-1bb6-a777-2f72-25a7ed9981dc@fleshgrinder.com>
 <HE1PR02MB1052BE9280284A99AA53466BBAD90@HE1PR02MB1052.eurprd02.prod.outlook.com>
 <4f803b88-813d-dacb-db05-248b5e372899@fleshgrinder.com>
 <HE1PR02MB1052131D94EA1956D5F785A1BAD90@HE1PR02MB1052.eurprd02.prod.outlook.com>
 <CAL=_i_kvGz6K217VUmyk9HU28BHTOXkMXtL7nJ8H7U8BRoHq_Q@mail.gmail.com>
Message-ID: <12021a91-ccd8-4225-c1d8-66c64c7ebb4c@oracle.com>
Date: Tue, 27 Jun 2017 14:54:57 +1000
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:52.0)
 Gecko/20100101 Thunderbird/52.2.1
MIME-Version: 1.0
In-Reply-To: <CAL=_i_kvGz6K217VUmyk9HU28BHTOXkMXtL7nJ8H7U8BRoHq_Q@mail.gmail.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit
Content-Language: en-US
Subject: Re: [PHP-DEV] [RFC] [Vote] Doxygen
From: christopher.jones@oracle.com (Christopher Jones)



On 26/6/17 4:43 pm, Joe Watkins wrote:
> Morning,
>
> I also voted no for similar reasons to Anatol.
>
> This is not really a thing that needs a vote, this is a thing that requires
> the handful of people who are actually able to document ZE to spend
> considerable time doing so. In addition it requires a commitment from the
> community of developers to continue to maintain, and introduce inline
> documentation with new code.
>
> Additionally, I'm a little concerned that an RFC that has the potential to
> touch every single source file has gone to vote with a simple majority. It
> would seem that we are deciding that new code must be documented in this
> specific way, to say nothing of the massive task of documenting existing
> code. That would seem to be a decision that could effect everybody that
> works on PHP in perpetuity and a simple majority is nothing like a strong
> enough consensus.
>
> Cheers
> Joe

I agree that although the intention is good, the burden on developers is likely
to cause it to be unsuccessful.  The current state of inline documentation is
partly the result of the culture of PHP, but also the general reluctance of
developers to create documentation :(

Chris

>
> On Sat, Jun 24, 2017 at 10:59 PM, Anatol Belski <weltling@outlook.de> wrote:
>
>>
>>> -----Original Message-----
>>> From: Fleshgrinder [mailto:php@fleshgrinder.com]
>>> Sent: Saturday, June 24, 2017 11:34 PM
>>> To: php-internals <internals@lists.php.net>; Anatol Belski
>>> <weltling@outlook.de>
>>> Subject: Re: [PHP-DEV] [RFC] [Vote] Doxygen
>>>
>>> On 6/24/2017 11:28 PM, Anatol Belski wrote:
>>>> I voted no, because it is too short term and I'd see a productivity
>>>> drop having such an obligation suddenly right in place for 7.2. To
>>>> implement the change, there's more than just to put the doc into the
>>>> source. Every piece of code needs to be revisited by someone who
>>>> understands it.
>>>>
>>>> I'm not saying the current situation is better than the aim, but to be
>>>> realistic - the change needs a culture to be developed. It is clear,
>>>> that some know doxygen, but I believe maintaining the doc will be
>>>> still a huge effort for many contributors. If some patch were in place
>>>> - at least one would have a source for learning by watching, so it
>>>> would reduce the learn hurdle ? Without being familiar with Doxygen
>>>> the actual productivity will for sure suffer.
>>>>
>>>> Neither there's a patch covering at least the very core, nor there's a
>>>> strategy for the transition period. I can imagine, that even if the
>>>> RFC is voted positive, many contributors not familiar with doxygen
>>>> won't have time to complete the doc part. The intention good, but the
>>>> assertion might be hard. I might be wrong, but ATM I think the
>>>> intention is good, whereby the RFC implementation owes IMHO some
>>>> elaborated strategy.
>>>>
>>>> Regards
>>>>
>>>> Anatol
>>>>
>>> We are only voting that we want to use Doxygen for documentation as a
>>> format, not that documentation is a must for PRs or anything. From the
>> RFC:
>>>> This RFC does not propose any big documentation fest where development
>>>> is halted and everybody starts writing documentation. Rather to start
>>>> documenting in the future, as well as while refactoring or rewriting
>>>> existing code.
>>> Hence, it would be nice to write a little while one is working on
>> something
>>> anyways.
>>>
>>> There is no must to document!
>>>
>> Ok, that was my very concern. Documenting the existing code would also
>> need profound reviews.
>>
>>> There is a must that IF you document, that it must use Doxygen.
>>>
>>> That's what we are voting on. Everybody has plenty of time to get
>> acquainted
>>> with Doxygen and we can create follow-up RFCs with clearer rules on how
>> to
>>> document (if need be).
>>>
>> I'd still see an issue, the formulation is a bit slack. If I don't have
>> to, probably I'd spare 10 minutes I'd have to spend, because a bug
>> investigation or implementation would take a triple time or more. Depending
>> on what it takes for me personally in the sum, it could be at least 1 hour
>> a week, most even 8 hours in a week, that's huge. I'd still say, it needs a
>> strategy and the community says it's a must. Otherwise, the doc might come
>> not from a person who implements or understands it. Or - the doc would only
>> reflect function signatures, which are anyway browsable with lxr, by grep
>> directly, or the code can be studied from the source.
>>
>> Thanks
>>
>> Anatol
>>
>>

-- 
http://twitter.com/ghrd