Re: [PHP-DEV] [RFC] [Vote] Doxygen
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 wrote: -Original Message- From: Fleshgrinder [mailto:p...@fleshgrinder.com] Sent: Saturday, June 24, 2017 11:34 PM To: php-internals ; Anatol Belski 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 -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DEV] [RFC] [Vote] Doxygen
No from me as well. This is wagging the dog by the tail. Picking a documentation format is the very least of the concerns here. It would be wonderful to have better internal API documentation, but putting up any sort of structural restriction like limiting it to a specific header-based format, isn't going to make such documentation more likely. I couldn't care less which format such documentation is in. If the folks who are capable of writing decent API docs want to do it in Microsoft Word, LaTeX or some weird SGML format, great! Whatever format it might appear in we can use and convert to whatever makes sense at that point. -Rasmus On Mon, Jun 26, 2017 at 5:26 AM, Kalle Sommer Nielsen wrote: > HI Joe, > > 2017-06-26 8:43 GMT+02:00 Joe Watkins : > > 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. > > I'm in the same boat as you and Anatol here. > > I think it is important to note that all who actively work on the > Core/Engine have no except for Stas, which also should be a good > indicator that we should be concerned. > -- > regards, > > Kalle Sommer Nielsen > ka...@php.net > > -- > PHP Internals - PHP Runtime Development Mailing List > To unsubscribe, visit: http://www.php.net/unsub.php > >
Re: [PHP-DEV] [RFC] [Vote] Doxygen
HI Joe, 2017-06-26 8:43 GMT+02:00 Joe Watkins : > 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. I'm in the same boat as you and Anatol here. I think it is important to note that all who actively work on the Core/Engine have no except for Stas, which also should be a good indicator that we should be concerned. -- regards, Kalle Sommer Nielsen ka...@php.net -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DEV] [RFC] [Vote] Doxygen
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 wrote: > > > > -Original Message- > > From: Fleshgrinder [mailto:p...@fleshgrinder.com] > > Sent: Saturday, June 24, 2017 11:34 PM > > To: php-internals ; Anatol Belski > > > > 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 > >
RE: [PHP-DEV] [RFC] [Vote] Doxygen
> -Original Message- > From: Fleshgrinder [mailto:p...@fleshgrinder.com] > Sent: Saturday, June 24, 2017 11:34 PM > To: php-internals ; Anatol Belski > > 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
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! 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). -- Richard "Fleshgrinder" Fussenegger signature.asc Description: OpenPGP digital signature
RE: [PHP-DEV] [RFC] [Vote] Doxygen
Hi, > -Original Message- > From: Fleshgrinder [mailto:p...@fleshgrinder.com] > Sent: Friday, June 23, 2017 9:20 PM > To: php-internals ; christopher.jo...@oracle.com > Subject: Re: [PHP-DEV] [RFC] [Vote] Doxygen > > On 6/23/2017 5:12 AM, Christopher Jones wrote: > > That kind of detail belongs in the RFC. > > > > A link to existing 'prior art' would have rounded the picture out and > > let people decide between alternatives of internal vs external doc. > > E.g. link to https://wiki.php.net/internals/references > > > > Also, is this for core and for extensions? Or for core only? What > > about PECL extensions not part of the PHP bundle? > > > > In summary, see point 8 of > > https://blogs.oracle.com/opal/the-mysterious-php-rfc-process-and-how-y > > ou-can-change-the-web > > > > > > Chris > > > > Hi Chris! > > I agree and if I would have thought about it, I would have included it. > (This is not an excuse, just the honest truth.) I can create a follow up RFC > with > more detailed rules, or maybe we wait a little so that everybody can get > acquainted with Doxygen first. > > Regarding PECL: I clearly state in the introduction "for the C sources of > PHP" (in > other words, everything inside the php-src repository) and I would stick to > that. > PECL authors should be allowed, like Composer authors, to do whatever they > want. PECL extensions that are to be included in "the C sources of PHP" should > of course adopt the style, like it is already today in regards to the code > style. > Otherwise we can never get to the "future scope" of actually generating docs > for browsing. > 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
Re: [PHP-DEV] [RFC] [Vote] Doxygen
On 6/23/2017 5:12 AM, Christopher Jones wrote: > That kind of detail belongs in the RFC. > > A link to existing 'prior art' would have rounded the picture out and let > people decide between alternatives of internal vs external doc. > E.g. link to https://wiki.php.net/internals/references > > Also, is this for core and for extensions? Or for core only? What > about PECL extensions not part of the PHP bundle? > > In summary, see point 8 of > https://blogs.oracle.com/opal/the-mysterious-php-rfc-process-and-how-you-can-change-the-web > > > Chris > Hi Chris! I agree and if I would have thought about it, I would have included it. (This is not an excuse, just the honest truth.) I can create a follow up RFC with more detailed rules, or maybe we wait a little so that everybody can get acquainted with Doxygen first. Regarding PECL: I clearly state in the introduction "for the C sources of PHP" (in other words, everything inside the php-src repository) and I would stick to that. PECL authors should be allowed, like Composer authors, to do whatever they want. PECL extensions that are to be included in "the C sources of PHP" should of course adopt the style, like it is already today in regards to the code style. Otherwise we can never get to the "future scope" of actually generating docs for browsing. -- Richard "Fleshgrinder" Fussenegger signature.asc Description: OpenPGP digital signature
Re: [PHP-DEV] [RFC] [Vote] Doxygen
On 22/6/17 1:43 am, Fleshgrinder wrote: On 6/21/2017 5:38 PM, Nikita Popov wrote: Can you please clarify where functions that are declared in a header and defined in a source file should be documented? I believe the usual recommendation is to document in the source file, because it's closer to the implementation and thus more likely to be updated. On the other hand, documentation in headers only is more useful if you're just browsing code and not using generated output. Nikita The documentation should go into the header file. Source files actually must not have documentation, because everything in there is private anyways. Unless it is exported via a header file that is. Doxygen will automatically inherit the documentation (no @inheritDoc necessary), because it understands the C code in C mode. That kind of detail belongs in the RFC. A link to existing 'prior art' would have rounded the picture out and let people decide between alternatives of internal vs external doc. E.g. link to https://wiki.php.net/internals/references Also, is this for core and for extensions? Or for core only? What about PECL extensions not part of the PHP bundle? In summary, see point 8 of https://blogs.oracle.com/opal/the-mysterious-php-rfc-process-and-how-you-can-change-the-web Chris Documentation should never document what the implementation does, only how it can be used. This gets blurry if you implement a particular, standardized algorithm (like the UUIDs) where the actual implementation suddenly becomes an important part of information that should go into the documentation. In other words, refactoring and other changes in a functions body should not require changes of the documentation. A usage change usually directly translates to a breaking change. A situation in which many places require updates (e.g. CHANGELOG, NEWS, ...) and not something a dev should do without thinking about the implications of doing so. -- http://twitter.com/ghrd -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DEV] [RFC] [Vote] Doxygen
On 6/21/2017 5:38 PM, Nikita Popov wrote: > Can you please clarify where functions that are declared in a header and > defined in a source file should be documented? I believe the usual > recommendation is to document in the source file, because it's closer to > the implementation and thus more likely to be updated. On the other hand, > documentation in headers only is more useful if you're just browsing code > and not using generated output. > > Nikita > The documentation should go into the header file. Source files actually must not have documentation, because everything in there is private anyways. Unless it is exported via a header file that is. Doxygen will automatically inherit the documentation (no @inheritDoc necessary), because it understands the C code in C mode. Documentation should never document what the implementation does, only how it can be used. This gets blurry if you implement a particular, standardized algorithm (like the UUIDs) where the actual implementation suddenly becomes an important part of information that should go into the documentation. In other words, refactoring and other changes in a functions body should not require changes of the documentation. A usage change usually directly translates to a breaking change. A situation in which many places require updates (e.g. CHANGELOG, NEWS, ...) and not something a dev should do without thinking about the implications of doing so. -- Richard "Fleshgrinder" Fussenegger signature.asc Description: OpenPGP digital signature
Re: [PHP-DEV] [RFC] [Vote] Doxygen
On Sat, Jun 17, 2017 at 9:53 AM, Fleshgrinder wrote: > Hi! > > I started voting on the Doxygen RFC: > > https://wiki.php.net/rfc/doxygen > > -- > Richard "Fleshgrinder" Fussenegge > Can you please clarify where functions that are declared in a header and defined in a source file should be documented? I believe the usual recommendation is to document in the source file, because it's closer to the implementation and thus more likely to be updated. On the other hand, documentation in headers only is more useful if you're just browsing code and not using generated output. Nikita
Re: [PHP-DEV] [RFC] [Vote] Doxygen
On 6/21/2017 4:13 AM, Christopher Jones wrote: > > On 17/6/17 5:53 pm, Fleshgrinder wrote: >> Hi! >> >> I started voting on the Doxygen RFC: >> >> https://wiki.php.net/rfc/doxygen >> > Did I miss seeing when the vote ends? > > Chris > You did not, I forgot to mention it. The vote will close on July 1 at around 6 PM. :) -- Richard "Fleshgrinder" Fussenegger signature.asc Description: OpenPGP digital signature
Re: [PHP-DEV] [RFC] [Vote] Doxygen
On 6/19/2017 2:31 PM, Jakub Zelenka wrote: > On Sat, Jun 17, 2017 at 8:53 AM, Fleshgrinder wrote: > >> Hi! >> >> I started voting on the Doxygen RFC: >> >> https://wiki.php.net/rfc/doxygen >> >> > I just wanted to send my feedback and the reason why I voted "yes". First > of all I don't really like adding too much documentation to the code (I'm > actually talking about the PR which seems really too much IMHO). However I > think that this RFC is more about having a standard for documenting > exported functions which would be really good in my opinion and I think > Doxygen is really good one (one can easily see that in Apache httpd for > example). I think that few lines is usually enough and sometimes it is > useful to have a note about the used parameters. What I want to say is that > we shouldn't think about the RFC as accepting the proposed PR. It should be > treated on case by case bases and over documented code should be still > rejected. > > Cheers > > Jakub > Thanks for the feedback, the intend of this RFC is exactly as you understood it. It's not a +1 for the linked PR. As I said to Nikic, whether a particular PR is acceptable or not must be part of a code review. -- Richard "Fleshgrinder" Fussenegger signature.asc Description: OpenPGP digital signature
Re: [PHP-DEV] [RFC] [Vote] Doxygen
On 17/6/17 5:53 pm, Fleshgrinder wrote: Hi! I started voting on the Doxygen RFC: https://wiki.php.net/rfc/doxygen Did I miss seeing when the vote ends? Chris -- http://twitter.com/ghrd -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DEV] [RFC] [Vote] Doxygen
On Sat, Jun 17, 2017 at 8:53 AM, Fleshgrinder wrote: > Hi! > > I started voting on the Doxygen RFC: > > https://wiki.php.net/rfc/doxygen > > I just wanted to send my feedback and the reason why I voted "yes". First of all I don't really like adding too much documentation to the code (I'm actually talking about the PR which seems really too much IMHO). However I think that this RFC is more about having a standard for documenting exported functions which would be really good in my opinion and I think Doxygen is really good one (one can easily see that in Apache httpd for example). I think that few lines is usually enough and sometimes it is useful to have a note about the used parameters. What I want to say is that we shouldn't think about the RFC as accepting the proposed PR. It should be treated on case by case bases and over documented code should be still rejected. Cheers Jakub
