+- CodeIgniter Forums (https://forum.codeigniter.com)
+-- Forum: External Resources (https://forum.codeigniter.com/forumdisplay.php?fid=7)
+--- Forum: Learn More (https://forum.codeigniter.com/forumdisplay.php?fid=15)
+--- Thread: Good reference for learning PHPDoc? (/showthread.php?tid=82068)
Good reference for learning PHPDoc? - datamweb - 06-08-2022
Hi friends,
I have no knowledge of PHPDoc.
Can you provide a reference for teaching it?
Why should we use it, where should it be used and ...
Please introduce a suitable reference for the beginner.
Thanks
RE: Good reference for learning PHPDoc? - captain-sensible - 06-08-2022
hello datamweb take my comment with a good dose of humour
Is this homework ? or a rhetorical question ;i only ask since you state "why should we use it" which sort of implicitly implies someone has told you to use it or ..
Normally someone identifies an issue, tries to solve it themselves and if they can't ask a question.
Your question alludes to "how you document or comment on code , to a standard" ? That is more likely to come onto play if your working with a team and the manager wants documentation to the same standard .
IN my case all I do is use 2 forward slashes to comment code or other recognised php ways
Docs are here :
https://www.phpdoc.org/
RE: Good reference for learning PHPDoc? - kenjis - 06-08-2022
There are two draft PSRs:
https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md
https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc-tags.md
From https://www.php-fig.org/psr/#draft
Quote:Why should we use it, where should it be used
Specifying Types is a good practice. It helps developers to understand code, reduce bugs, and helps static analysis or IDE.
In the old age, there is no type declaration in PHP:
https://www.php.net/manual/en/language.types.declarations.php
So people used Doc comment, showing types as special comments.
@var, @param, @return, ...
Now PHP has type declaration, but not all the Doc comments cannot be specified as type declarations.
For example, if you don't use PHP 8.0 or later, you can't use Union Types:
https://www.php.net/manual/en/language.types.declarations.php#language.types.declarations.composite.union
So when we can't specify types with type declaration, we still use PHPDoc.
RE: Good reference for learning PHPDoc? - datamweb - 06-08-2022
(06-08-2022, 02:50 AM)captain-sensible Wrote: That is more likely to come onto play if your working with a team and the manager wants documentation to the same standard .
Docs are here :
https://www.phpdoc.org/
thank you.
It seems I have to spend a lot of time studying PHPDoc.
(06-08-2022, 05:44 PM)kenjis Wrote: There are two draft PSRs:
https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md
https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc-tags.md
From https://www.php-fig.org/psr/#draft
Quote:Why should we use it, where should it be used
Specifying Types is a good practice. It helps developers to understand code, reduce bugs, and helps static analysis or IDE.
In the old age, there is no type declaration in PHP:
https://www.php.net/manual/en/language.types.declarations.php
So people used Doc comment, showing types as special comments.
@var, @param, @return, ...
Now PHP has type declaration, but not all the Doc comments cannot be specified as type declarations.
For example, if you don't use PHP 8.0 or later, you can't use Union Types:
https://www.php.net/manual/en/language.types.declarations.php#language.types.declarations.composite.union
So when we can't specify types with type declaration, we still use PHPDoc.
Thank you very much Kenjis,
I do not know how to thank you for your kindness.