Use phpDocumentor

[sagikazarmark]

Do we want to use phpDocumentor?

@mekras raised the idea.

Honestly, I am not sure it is even possible given that the project is separated into several repos, but would be nice to have.

[mekras]

I prefer http://www.apigen.org/.

[sagikazarmark]

Looks great.

[dbu]

myself i use an IDE to develop, so i never look at generated docs. but if somebody wants to set apigen / phpdocumentor up on the website, i have nothing against. i do appreciate good phpdoc on our code, so it can't hurt.

[sagikazarmark]

@mekras how does phpdoc/apigen behave with symfony-like file headers. Actually I decided to remove them as I saw no real added value.

[mekras]

apigen is very tolerant to headers. phpdoc requires both (starting with "/**"), and requires at least summary in each header.

[mekras]

I usually try to write PHPDoc comments following the phpDocumentor rules, because they are well described and more strict. So these comments can be used by various tools, not only by phpdoc/apigen (e. g. IDEs).