Hi!
I started voting on the Doxygen RFC:
https://wiki.php.net/rfc/doxygen
--
Richard "Fleshgrinder" Fussenegger
Hi!
I started voting on the Doxygen RFC:
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
Hi!
I started voting on the Doxygen RFC:
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
Hi!
I started voting on the Doxygen RFC:
Did I miss seeing when the vote ends?
Chris
Hi!
I started voting on the Doxygen RFC:
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
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
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
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.
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/referencesAlso, 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-webChris
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
Hi,
-----Original Message-----
From: Fleshgrinder [mailto:php@fleshgrinder.com]
Sent: Friday, June 23, 2017 9:20 PM
To: php-internals internals@lists.php.net; christopher.jones@oracle.com
Subject: Re: [PHP-DEV] [RFC] [Vote] DoxygenThat 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/referencesAlso, 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-webChris
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
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
-----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] DoxygenI 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
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
-----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] DoxygenI 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
HI Joe,
2017-06-26 8:43 GMT+02:00 Joe Watkins pthreads@pthreads.org:
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
kalle@php.net
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
HI Joe,
2017-06-26 8:43 GMT+02:00 Joe Watkins pthreads@pthreads.org:
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
kalle@php.net
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
-----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] DoxygenI 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