This is mainly for programmers, for others it is more info, so that if they happen to get to some programming, they know to write it there too. In order to improve the code readability, we need to start writing some documentation for functions (or even classes) in the code: PhpDocs.
Reason:
- Tt gives better hints if it knows the parameters (in 7.1 and below it didn't know how to type in arguments and almost anything was a problem, so it can be put at least into phpDocs, where php sees it only as a pure comment, which it ingores)
- If someone else comes to this function, then according to the description at least somehow knows what it does or at least what it should do, what it returns, what values it needs and what values it can acquire
- Readability -> this can also be the difference between overlooking a feature we would otherwise need or not.
There is no golden rule for writing descriptions to functions (meant purely as descriptions. Of course php docs have their own values that we can use like @author or @param etc. ), but please make sure you all set the code style to make it easier to read, and that when one aligns and then the other, it doesn't create 30 changes just because of spaces (in the future it would like to unify everything so that there are not 40 changes in the file just because someone uses tab for indentation and someone uses spaces)
Settings: (applies only to those who have phpstorm, the others have to fix it manually somehow) open settings ctrl + alt + S -> search for "phpdocs" and in the "code style" tab you will find "PHP" -> after clicking on it the same as in the picture below will appear (it is also good to check at the top that the selected scheme is default or what you use everywhere on other projects). Just compare it with the image and then click apply and ok (the ok button should be enough) and you're all set.
To use it, just go to the function and either right click on the fnc name, choose "show context actions" and select "generate PHPDocs" or right above the function you want to add the docs for, type /** and press ENTER. This will create the base documentation.
Then add some description, then @params add the data type (if you are sure that the type will be there, if it can be null, it is given as string|null or ?string -> the documentation converts to string|null anyway. if there are more types, it is marked with | ) and description (briefly, what the arg does in the function).
If the @param is an array, it is necessary to write it in the description (unfortunately it cannot be written better, but it is necessary to at least indicate what it is), i.e.: if I enter an array that has the product id as a call and the name as a value, I add the part to the beginning of the description [product_id => product_name].
For @param, please always specify the data type first, then the variable name and finally the description.
Finally, if you have everything set above, it is enough to select the whole documentation and press ctrl + alt + L to format only the text in the documentation without formatting the whole document unnecessarily, that is, if it is not necessary to select the documentation.
A little example
In general it is important to look back at it and say, if I myself can get what it does or at least what it should do and what I need to send data to it to make it do what it should.
AND PLEASE WRITE DESCRIPTIONS IN ENGLISH