====== PHP RFC: Doxygen ======
  * Version: 1.0
  * Date: 2017-05-30
  * Author: Richard Fussenegger, php@fleshgrinder.com
  * Status: Declined
  * First Published at: http://wiki.php.net/rfc/doxygen

===== Introduction =====
Proposal to adopt the [[http://www.stack.nl/~dimitri/doxygen/|Doxygen]] documentation style for the C sources of PHP

> […] static typing appears to be even more effective when documentation is added, as both helps appear to reinforce each other.
>
> — [[https://pdfs.semanticscholar.org/effb/65a255cf44e058cdada2168985a46f229e88.pdf|Stefan Endrikat, Stefan Hanenberg, Romain Robbes, and Andreas Stefik. 2014. How do API documentation and static typing affect API usability?]]

===== 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 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.

Doxygen supports multiple formats. However, only two are usable for us due to our requirement to be compatible with the C89 standard. This RFC proposes to use the JavaDoc style for two reasons:

  - There is extensive documentation available on how to write good Java Docs.
  - It is very close to PhpDoc, or even almost the same. This means that the barrier of entry for typical PHP developers is very low.

<code c>
/**
 * A brief description of what this structural element does.
 *
 * An extended description that goes into details about how to use it right, or
 * other things that are of interest to a fellow developer.
 *
 * ### Examples
 *
 * ```c
 * char *var = "Examples are the most important part!";
 * ```
 *
 * @see routine_name()
 * @param[out] output_argument where we store something.
 * @param[in] input_argument that is required to produce the output.
 * @return NULL if an error occurs, or something else.
 */
</code>

The exact features, as well as available tags, are explained in detail in the [[http://www.stack.nl/~dimitri/doxygen/manual/index.html|Doxygen documentation]] and will not be repeated in this RFC. A few recommendations regarding the style of the comments are maybe good:

  - Comments are placed before the structural element that should be documented, except for files (impossible, see below).
  - Comment lines should not exceed 80 columns.
  - An empty line should be placed between the first tag and the description.
  - Parameter documentation must not be aligned (maintenance hell).

A few visual examples:

<code c>
/** @file some/path/to/a/file.c
 *
 * This is a file comment at the start of a file.
 *
 * @author John Doe
 */

/** Short comments can stay inline. */
static const int ONE = 1;

/**
 * Summary
 *
 * Description
 *
 * ### Examples
 *
 * ```c
 * // example comments must use //
 * ```
 *
 * @param[out] arg1 bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
 *     bla bla bla bla bla bla bla.
 * @param[out] arg2 bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
 *     bla bla bla bla bla bla bla.
 * @param[in] arg3 bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
 *     bla bla bla bla bla bla bla.
 * @param[in] arg4 bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
 *     bla bla bla bla bla bla bla.
 * @return NULL on failure, some string otherwise.
 * @throws \Exception in PHP if situation a) or situation b).
 */
PHPAPI const char *hello_world(char *arg1, char *arg2, int arg3, int arg4);
</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 =====
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.

===== Proposed Voting Choices =====
Simple 50%+1 majority vote.

<doodle title="Document with Doxygen?" auth="fleshgrinder" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== References =====
  * [[http://news.php.net/php.internals/99312|Discussion]]
  * [[http://news.php.net/php.internals/99140|Pre-discussion]]