rfc:doxygen
Differences
This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
rfc:doxygen [2017/05/30 20:41] – created fleshgrinder | rfc: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, | * Author: Richard Fussenegger, | ||
- | * Status: | + | * Status: |
* First Published at: http:// | * First Published at: http:// | ||
===== Introduction ===== | ===== Introduction ===== | ||
Proposal to adopt the [[http:// | Proposal to adopt the [[http:// | ||
+ | |||
+ | > […] static typing appears to be even more effective when documentation is added, as both helps appear to reinforce each other. | ||
+ | > | ||
+ | > — [[https:// | ||
===== Proposal ===== | ===== Proposal ===== | ||
- | * https://github.com/ | + | 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/ |
- | * https://www.mantidproject.org/Visual_Studio_Doxygen_Setup | + | |
- | * https://marketplace.visualstudio.com/items? | + | |
- | Doxygen supports multiple formats. However, only two are usable for us due to our requirement to be compatible with the C89 standard. | + | 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, |
+ | |||
+ | 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. | ||
- | ====== JavaDoc style ====== | ||
<code c> | <code c> | ||
/** | /** | ||
- | | + | |
* | * | ||
- | * @param[in] | + | * An extended description that goes into details about how to use it right, or |
- | * @return NULL if an error occurs, or a handle for the file. | + | * other things that are of interest to a fellow developer. |
+ | * | ||
+ | * ### Examples | ||
+ | * | ||
+ | * ```c | ||
+ | * char *var = " | ||
+ | * ``` | ||
+ | * | ||
+ | * @see routine_name() | ||
+ | * @param[out] output_argument where we store something. | ||
+ | * @param[in] | ||
+ | * @return NULL if an error occurs, or something else. | ||
*/ | */ | ||
</ | </ | ||
- | A considerable advantage of the JavaDoc | + | The exact features, as well as available tags, are explained in detail in the [[http:// |
+ | |||
+ | - Comments are placed before the structural element | ||
+ | - Comment lines should not exceed 80 columns. | ||
+ | - An empty line should be placed between | ||
+ | - Parameter documentation must not be aligned (maintenance hell). | ||
+ | |||
+ | A few visual examples: | ||
- | ====== Qt Style ====== | ||
<code c> | <code c> | ||
- | /*! | + | /** @file some/path/to/a/file.c |
- | \brief Attempts | + | * |
+ | * This is a file comment at the start of a file. | ||
+ | * | ||
+ | * @author John Doe | ||
+ | */ | ||
- | \param[in] fname The full path name of the file to open. | + | /** Short comments can stay inline. */ |
+ | static const int ONE = 1; | ||
- | \return NULL if an error occurs, or a handle for the file. | + | /** |
- | */ | + | * 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 | ||
+ | | ||
+ | * @param[out] arg2 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 | ||
+ | | ||
+ | * @param[in] arg4 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 | ||
+ | */ | ||
+ | PHPAPI const char *hello_world(char *arg1, char *arg2, int arg3, int arg4); | ||
</ | </ | ||
+ | |||
+ | The following extended examples might be of interest too (they feature extensive documentation, | ||
+ | |||
+ | * [[https:// | ||
+ | * [[https:// | ||
===== Future Scope ===== | ===== Future Scope ===== | ||
Line 44: | Line 98: | ||
===== Proposed Voting Choices ===== | ===== Proposed Voting Choices ===== | ||
Simple 50%+1 majority vote. | Simple 50%+1 majority vote. | ||
+ | |||
+ | <doodle title=" | ||
+ | * Yes | ||
+ | * No | ||
+ | </ | ||
===== References ===== | ===== References ===== | ||
- | * [[http:// | + | |
+ | | ||
rfc/doxygen.1496176886.txt.gz · Last modified: 2017/09/22 13:28 (external edit)