On Sunday, 28 December 2014 at 17:22:50 UTC, Kiith-Sa wrote:
That's a good idea. I propose rule #1: Under no circumstances
will auto be allowed in any examples. The compiler should even
reject files in which they appear. One of the most frustrating
things is to read documentation with type T (completely
uninformative) followed by an example with auto.
Doesn't work with Voldemort types, stupid with LongClassName a
= new LongClassName(long, parameter, list). Use your brain, not
"under no circumstances" rules, when writing documentation.
Same as Params:/Returns: - they may not be useful for trivial
functions but are very useful with more complex ones. Again,
use your brain - "Will someone reading this thing I'm writing
here have any actual idea about how to use this function?"
So you're arguing that the existing documentation was written by
folks not using their brains? "Use your brain" doesn't work and
that is the reason rules are necessary. Same thing for "Will
someone reading this thing I'm writing here have any actual idea
about how to use this function?" Everyone has their own
definition of what can be understood. The person that wrote the
documentation that started this thread evidently thought the
explanation was sufficient. Without rules you have nothing.
