rfc:doxygen

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
rfc:doxygen [2017/06/01 19:02] – Changed status to Under Discussion fleshgrinderrfc:doxygen [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 3: Line 3:
   * Date: 2017-05-30   * Date: 2017-05-30
   * Author: Richard Fussenegger, php@fleshgrinder.com   * Author: Richard Fussenegger, php@fleshgrinder.com
-  * Status: Under Discussion+  * Status: Declined
   * First Published at: http://wiki.php.net/rfc/doxygen   * First Published at: http://wiki.php.net/rfc/doxygen
  
Line 14: Line 14:
  
 ===== Proposal ===== ===== Proposal =====
-The proposal is actually very simple: to start documenting the C sources of PHP with Doxygen comments. This RFC will not go into detail why proper API documentation is beneficial, [[https://pdfs.semanticscholar.org/effb/65a255cf44e058cdada2168985a46f229e88.pdf|science has the answer]]. Most developers are aware of this anyways, since they use technical documentation on their own every day. An attempt to document PHP internals was already started a few years back by Jefferson Gonzalez ([[https://github.com/jgmdev/phoxygen|see phoxygen at GitHub]]), but abandoned due to lack of support from others.+The proposal is actually very simple: to start documenting the C sources of PHP with Doxygen comments. This RFC will not go into detail why proper API documentation is beneficial, [[https://pdfs.semanticscholar.org/effb/65a255cf44e058cdada2168985a46f229e88.pdf|science has the answer]]. Most developers are aware of this anyways, since they use technical documentation on their own every day. An attempt to document PHP internals was already started a few years back by Jefferson Gonzalez ([[https://github.com/jgmdev/phoxygen|see phoxygen at GitHub]]), but abandoned due to a lack of spare time.
  
 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. The target audience of our documentation should be fellow developers who want to get started with PHP internals development, hence, examples are usually what is most important. There is (sadly) no awesome doc-testing feature available like Rust has it, but examples are still beneficial and spare people to search the Internet, or read one of the totally outdated books/online resources. 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. The target audience of our documentation should be fellow developers who want to get started with PHP internals development, hence, examples are usually what is most important. There is (sadly) no awesome doc-testing feature available like Rust has it, but examples are still beneficial and spare people to search the Internet, or read one of the totally outdated books/online resources.
Line 87: Line 87:
 PHPAPI const char *hello_world(char *arg1, char *arg2, int arg3, int arg4); PHPAPI const char *hello_world(char *arg1, char *arg2, int arg3, int arg4);
 </code> </code>
 +
 +The following extended examples might be of interest too (they feature extensive documentation, maybe even too much):
 +
 +  * [[https://github.com/Fleshgrinder/php-src/blob/c1067c9256959f9246daa7658a94fea0d612295e/ext/standard/php_uuid.h|H file]]
 +  * [[https://github.com/Fleshgrinder/php-src/blob/c1067c9256959f9246daa7658a94fea0d612295e/ext/standard/uuid.c|C file]]
  
 ===== Future Scope ===== ===== Future Scope =====
Line 93: Line 98:
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
 Simple 50%+1 majority vote. Simple 50%+1 majority vote.
 +
 +<doodle title="Document with Doxygen?" auth="fleshgrinder" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ===== References ===== ===== References =====
-  * [[http://news.php.net/php.internals/99140|Mailing list discussion]]+  * [[http://news.php.net/php.internals/99312|Discussion]] 
 +  * [[http://news.php.net/php.internals/99140|Pre-discussion]]
  
rfc/doxygen.1496343745.txt.gz · Last modified: 2017/09/22 13:28 (external edit)

Page Tools