I would like to know what style should we use in comments. I suppose that we should use phpDoc attributes but I would like to know which of them are necessary. The same question I have about Javascript.
We've moved the forum!
Please use forum.silverstripe.org for any new questions
(announcement).
The forum archive will stick around, but will be read only.
You can also use our Slack channel
or StackOverflow to ask for help.
Check out our community overview for more options to contribute.
Generally speaking, @param and @return are sufficient.
/**
* Short description of the class/method.
* This is a longer explanation of what the method does, be sure to include any
* assumptions that it makes; if it's designed to be called from some particular
* place, it's worth mentioning that too.
*
* @param something This is a variable What should it contain?
* @param other This is a variable. What should it contain?
* @return Explain the return value
*/
JavaScript doesn't currently have documentation auto-generated for it, but using a similar format to the PHP docs just keeps things consistent.
