Document usage of annotations

[Heaven31415]

This pull request introduced annotations: link They used to be called attributes.

This page in the crystal-book is the only one which mentions them: link Name of this page needs to be updated from attributes.md to annotations.md.

Annotation list used to be fixed, but now it's not. We have two categories of annotations: those provided by the compiler (built-in) and those provided by users.

I think it would be nice to create two separate pages, one describing compiler provided annotations (which we already have) and another about those provided by the user.

I think the article about user defined annotations should show:

• how to define an annotation
• where you can place an annotation (you can place them on top of instance variables, class variables, methods and types)
• how to query an annotation
• that you can override annotations
• a few examples of annotations (one for every possible case)
• usage examples and why you might need them
• that they are used for JSON and YAML serialization in std.

If I'm missing something or anything is wrong, tell me. This way we can make it a lot easier to write about them, especially if we have a solid plan.

If you want to find out more about annotations, check this out:

• Allow annotations on methods
• Annotations: add spec for overriding an annotation usage
• Compiler: allow annotations inside enums
• Fix: annotation check failure when other annotations are present

[wooster0]

The inbuilt compiler annotations should be removed from the docs since they will be documented in the API docs as far as I understood. As a beginning there's this PR which adds Deprecated annotation documentation: #7650 to the API docs.

[straight-shoota]

@r00ster91 Annotations understood by the compiler should be mentioned both in the API docs and language reference. The API docs should focus on how to use them in code and the language reference on how the compiler treats them.

[Blacksmoke16]

Writing this up now, will make a PR in next few days once it's done.