search

phpDocumentor / fig-standards

Standards either proposed or approved by the Framework Interop Group
http://www.php-fig.org/
Other
360 stars 85 forks source link

File- or page-level DocBlock needs explanation. #101

Closed Fleshgrinder closed 6 years ago

Fleshgrinder commented 9 years ago

I always wondered what it's good for and I couldn't find an answer in the PSR, but Wikipedia has one in their PHPDoc article. However, they use the term page-level DocBlock and the only reference in the PSR uses the term file.

I think it would be could to clarify the term and what this kind of documentation is good for. Clearly a file is stated as a structural element, but all the limitations and constraints that are mentioned on Wikipedia are not even mentioned in the PSR.

ashnazg commented 6 years ago

Current drafts only mention file, so the page ambiguity is gone.

On the "what's it good for" question, maybe some why-reasoning should be added.

neuro159 commented 6 years ago

We discussed it briefly during the phproundtable podcast - AFAIR consensus was that there are NO good cases for this. That includes the jokes about huge license agreement on top of file)

PhpStorm never supported this in all the years and we can not recall any requests.

Also as we discussed - no one renders docs to HTML anymore - so it's mostly ignored. You can still put it - for human - but there is no reference anywhere in code that will show (as quick doc)... may be if there were an include somewhere it would be nice to get that header as quick doc on it.. but that code style is not much used in modern codebases.

Especially considering the extra complicated logic in that Wikipedia article required to make it render on top of rendered doc HTML pages - lets drop it?

ashnazg commented 6 years ago

The file-level docblock is so prevalent historically, I'm not sure I want to completely leave it out. We at least have it described/defined right now. We can certainly say it's allowed but not recommended, maybe even call it deprecated.

neuro159 commented 6 years ago

"No special purpose" + guidelines like "put license to appropriate folder"

ashnazg commented 6 years ago

If this needs to be pursued further, please bring this up as a new thread on the FIG mailing list for discussion -- https://groups.google.com/forum/#!forum/php-fig