> You made an example of how not to write documentation and then you shown that the code was better without. Both code snippets are equally documented. That tr

> You made an example of how not to write documentation and then you shown that the code was better without. Both code snippets are equally documented. That triple slash thing is a doc comment and the type annotations will be also used by dart doc. Furthermore, those type annotations will be used by the IDE right away. It will tell me if I pass something of the wrong type or if I do something silly with the return value. That type information will be also shown in call tips. I can also run my stuff in checked mode during development, which will make sure that everything is used correctly. That's the advantage of having this kind of annotations baked into the language itself. It's a lot less annoying to write and, since it's standardized, every tool can use this information, too. Since this stuff is optional, you can gradually add them as you go. You can quickly prototype something and if it worked as intended, you can add some types while you clean it up.