• Version: 1.0
• Date: 2017-05-30
• Author: Richard Fussenegger, php@fleshgrinder.com
• Status: Draft
• First Published at: http://wiki.php.net/rfc/doxygen

Proposal to adopt the Doxygen documentation style for the C sources of PHP

• https://github.com/jgmdev/phoxygen
• https://www.mantidproject.org/Visual_Studio_Doxygen_Setup
• https://marketplace.visualstudio.com/items?itemName=JasonWilliams.AtomineerProDocumentationTrial

Doxygen supports multiple formats. However, only two are usable for us due to our requirement to be compatible with the C89 standard.

/**
 * Attempts to open the given file for reading.
 *
 * @param[in] fname The full path name of the file to open.
 * @return NULL if an error occurs, or a handle for the file.
 */

A considerable advantage of the JavaDoc style is that it matches the style of PhpDoc a lot. This means that PHP users who want to contribute to internals have it easier to get accustomed with it.

/*!
\brief Attempts to open the given file for reading.
 
\param[in] fname The full path name of the file to open.
 
\return NULL if an error occurs, or a handle for the file.
*/

Generating documentation and actually publishing it online for users to browse. We could publish them directly on GitHub (free hosting) or create a separate section within the official PHP website where they are accessible.

Simple 50%+1 majority vote.

• Mailing list discussion