Improve readability of annotation syntaxes

リンク先の annotations/#understanding-this-page ページから始め、issue に示されている複雑な構文の例を確認してください。issue では、推奨する置き換えも明確な完了テストも定義されていません。完了とするには、より読みやすい記法について合意し、ドキュメントの例を更新する必要があります。

The method currently used for describing how to use annotations can be easy to understand at times:
---@type <type>

And also impossible for mere mortals to understand:
---@cast <value_name> [+|-]<type|?>[, [+|-]<type|?>...]
---@overload fun([param: type[, param: type...]]): [return_value[,return_value]]

There must be a better way to represent these more complex syntaxes while also not using symbols regularly in use (<, >, (, ), [, ], {, }, @, #, -, +, =, :, ", ,, ., ?). Although now that I have listed some in-use symbols, I realize we really are quite limited. It is hard to explain a syntax that uses many symbols… using symbols.

I'm open to any suggestions on how this can be improved 🙂