On Friday, 18 December 2015 at 07:37:40 UTC, Jacob Carlborg wrote:
On 2015-12-18 00:50, Andrei Alexandrescu wrote:
* Many functions don't have "Parameters:", "Returns:", or
"Throws:"
sections. Those that respectively take parameters, return
non-void, or
throw, should have one each.
I think we need to be better at enforcing this in the pull
requests. I see a lot of this [2] in PR's.
After further changes I was able to add `Params:` and `Returns:`
with some valuable information, but it also comes with a fair
amount of redundancy. I think a lot of our current functions have
more than adequately documented parameters and return values,
just without using sections. Some redundancy can be a good thing,
but for most of those functions I don't see how simple-mindedly
adding purely redundant information is impactful.
The important thing is not those sections but that parameters and
return values are documented.
