Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
API documentation v2 #58
Hello fellow @hoaproject/hoackers and users!
The API documentation is a mess, and useless. Not specifically in Hoa, but in the majority of PHP projects. Recently, I learned from Rust, Elm, Haskel, Caml… and they have a nice usage of it. I would like to change the way we write API documentation in Hoa.
What is “API documentation”? Basically everything written in the code. Not only the doc-comment on functions, classes, attributes, or methods, but everything.
First, let's start by defining the documentation format. HTML is awesome and would be the best, but it is hard to read in the code (HTML in comment of PHP, too much syntaxes). Moreover, we do not need particular semantics. So markdown is the format we will use. Of course, there are several versions of Markdown, so maybe we will choose CommonMark, don't know what is the best move here.
Elements of the documentation
Explain what the class does, why it exists, how does it interact with others, examples, links to resources like RFC, online documentations, explain the design, explain the decision, explain the performance impact, design and decisions etc.
Provide at least one example about how to use it.
Explain what it holds, how it interacts with other, why it exists, design decision etc. If this is structural type, explain all its possible forms. Provide examples too.
Method and function documentations
Explain what the function does, why it exists, how does it interact with others, when should we call it, why, performance impact, design decisions etc.
Provide examples too, if possible for all of them.
Structure of a documentation element
A document element has different section in it, like:
There are special sections in this format:
These sections are not mandatory!
No more PHPDoc?
Yes. Removed. We have types in PHP 7, we have meaningful argument names, PHPDoc is useless. The first part of a method documentation can explain what the argument does. More importantly, if this is not possible to understand what a method/function does just by reading its name and its argument names, then we have an issue.
This was referenced
Feb 16, 2017
@Hywan I don't get your point here! What do you mean by we have an issue if we understand what a method/function does?
Except that the RFC LGTM
@Hywan great RFC, it will open the doors for some cool new tools :)
This is indeed a good argument in favor of removing PHPDoc. Unfortunately, this feature (type-hinting on class and scalars) does not cover all use cases on all PHP versions: think about nullable return.
We will only get this feature when the related RFC will be implemented and merged in php-src. And even with this feature being merged, you won't be able to use it unless you drop support for PHP < 7.2 (or more).
Think twice before removing every PHPDoc annotations, especially
Finally, I don't know if IDEs can infer thrown exceptions. If not, it could be interesting to keep
@jubianchi The IDE part is also very interesting. Should we write plugins to support Praspel? Heavy, long, not gonna be used I guess… so we will be marginalized, and this is a not a good thing.
I said I will come back to “if we target the latest PHP version”. Well, we have this discussion currently, http://discourse.hoa-project.net/t/drop-php-5-5-in-favor-php-7/234/2. If we need PHP 7.1, then, why not targeting 7.1. The project will still work anyway, people will not receive new updates, that's all. Popular libraries are stable, most of the others are stable too, we can drop 5.x, and target 7.1 or 7.2 directly. We will need time to implement all these RFC, particularly this one. We should not restrict ourselves on a version number that will be outdated when the RFC implementation will be over.
In http://discourse.hoa-project.net/t/drop-php-5-5-in-favor-php-7/234/5?u=hywan, I made a recap about why we should jump to 7.1 directly.