Welcome Guest, Not a member yet? Register   Sign In
Good reference for learning PHPDoc?
#1

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
Reply
#2

(This post was last modified: 06-08-2022, 02:50 AM by captain-sensible.)

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/
CMS CI4     I use Arch Linux by the way 

Reply
#3

There are two draft PSRs:
https://github.com/php-fig/fig-standards.../phpdoc.md
https://github.com/php-fig/fig-standards...oc-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.t...ations.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.t...site.union

So when we can't specify types with type declaration, we still use PHPDoc.
Reply
#4

(This post was last modified: 06-08-2022, 11:20 PM by datamweb.)

(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.../phpdoc.md
https://github.com/php-fig/fig-standards...oc-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.t...ations.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.t...site.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.
Reply




Theme © iAndrew 2016 - Forum software by © MyBB