On 12/19/15 12:01 AM, Jakob Ovrum wrote:
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.
Agreed there's got to be measure in everything. I'm thinking in those cases the existing documentation should be reformatted with the standard sections.
When you do standard-formatted documentation for many functions at once, it seems kinda trite. But for folks who work on some program and want to look up one function, reliance on a standard uniform format is very helpful.
Andrei
