Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:99640
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain pthreads.org from 209.85.213.52 cause and error)
MIME-Version: 1.0
In-Reply-To: <HE1PR02MB1052131D94EA1956D5F785A1BAD90@HE1PR02MB1052.eurprd02.prod.outlook.com>
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>
Date: Mon, 26 Jun 2017 07:43:01 +0100
Message-ID: <CAL=_i_kvGz6K217VUmyk9HU28BHTOXkMXtL7nJ8H7U8BRoHq_Q@mail.gmail.com>
To: Anatol Belski <weltling@outlook.de>
Cc: Fleshgrinder <php@fleshgrinder.com>, php-internals <internals@lists.php.net>
Content-Type: multipart/alternative; boundary="94eb2c14950c23bc7c0552d743b1"
Subject: Re: [PHP-DEV] [RFC] [Vote] Doxygen
From: pthreads@pthreads.org (Joe Watkins)

--94eb2c14950c23bc7c0552d743b1
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

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

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 b=
e
> > > 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 plac=
e
> > > - at least one would have a source for learning by watching, so it
> > > would reduce the learn hurdle =F0=9F=98=8A Without being familiar wit=
h 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 developmen=
t
> > > 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. Dependi=
ng
> on what it takes for me personally in the sum, it could be at least 1 hou=
r
> 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 com=
e
> not from a person who implements or understands it. Or - the doc would on=
ly
> reflect function signatures, which are anyway browsable with lxr, by grep
> directly, or the code can be studied from the source.
>
> Thanks
>
> Anatol
>
>

--94eb2c14950c23bc7c0552d743b1--