3 ms·

You made an example of how not to write documentation and then you shown that the code was better without. That is not the point. Try to add content to the doc

by riquito 14y ago

You made an example of how not to write documentation and then you shown that the code was better without. That is not the point. Try to add content to the documentation, as "what is expected to be x?", then you can't remove it so easily anymore

polux 14y ago
The point is right now JS developers of big apps write this kind of comments because they are understood by tools like https://developers.google.com/closure/ https://developers.google.com/closure/.
TazeTSchnitzel 14y ago
Um, I think that's a type annotation for closure compiler, not a documentation comment.
- ahoge 14y ago
  The closure compiler uses doc comments. YUIDoc or JSDoc comments look pretty similar, for example. However, since this stuff isn't standardized, there are some differences between different flavors.
ahoge 14y ago
> 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.

3 ms·

You made an example of how not to write documentation and then you shown that the code was better without. That is not the point. Try to add content to the doc

by riquito 14y ago

polux 14y ago
The point is right now JS developers of big apps write this kind of comments because they are understood by tools like https://developers.google.com/closure/ https://developers.google.com/closure/.
TazeTSchnitzel 14y ago
Um, I think that's a type annotation for closure compiler, not a documentation comment.
- ahoge 14y ago
  The closure compiler uses doc comments. YUIDoc or JSDoc comments look pretty similar, for example. However, since this stuff isn't standardized, there are some differences between different flavors.
ahoge 14y ago
> 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.