Enhance documentation of Deprecated annotation (#16195)

Adds documentation for newly supported deprecation of types and aliases (#15962) and parameters (#15999).

Author: straight-shoota

src/annotations.cr

@@ -1,12 +1,31 @@
-# This annotation marks methods, classes, constants, and macros as deprecated.
+# This annotation marks features as deprecated.
 #
-# It receives an optional `StringLiteral` as single argument containing a deprecation notice.
+# It can annotate methods, macros, types, constants, aliases and method parameters.
+#
+# It receives an optional `StringLiteral` as single argument containing a
+# deprecation notice.
 #
 # ```
 # @[Deprecated("Use `#bar` instead")]
 # def foo
 # end
+#
+# @[Deprecated("Here may be dragons")]
+# class Foo
+# end
+
+# def foo(bar, @[Deprecated("Do not try this at home")] baz)
+# end
 # ```
+#
+# Deprecations are shown in the API docs and the compiler prints a warning when
+# using a deprecated feature.
+#
+# Deprecated types only trigger a warning when they are actually _used_ (e.g.
+# calling a class method), not when they're just part of type restriction, for
+# example.
+# Deprecated parameters only trigger a warning when the particular parameter is
+# passed in a call. Calls without this parameter are unaffected.
 annotation Deprecated
 end