Merge: annotations: introduce `example` annotation
## Motivations
When looking at the nit libraries, it's not rare to find external files used only to store examples that cannot be expressed as docunit.
The `example` annotation aims at tag pieces of code that may be considered as examples and thus be:
1. ignored be the compilation tools
2. used by documentation tools (and testing tools)
## Why a new annotation?
Rather than the `examples/` folder convention?
1. Examples can now be included directly in the module code if needed
2. Makes it easier to separate real code example from helper code and example tests
3. More flexibility in project organization and namming
4. To be coherent with the `test` annotation
## How to use it?
Simply tag the MEntity with `example`:
~~~nit
module my_example_module is example
~~~
Can also be applied on classes and methods:
~~~nit
module my_module # is not example
# Abstract class A, we should provide an example of subclass...
# So let's see `ExampleA`.
abstract class A
end
# This class provides an example of how to sublass A.
class ExampleA is example
super A
end
class C
# This method provides an example of how to instantiate `A` sublcasses
fun example_init_a is example do
var a: A = new ExampleA
end
end
~~~
## Incoming work
This PR only introduces the annotation and applies it to the existing source code.
Next PR will make tools like nitweb, nitdoc and nitx use it (via commands #2580).
Pull-Request: #2581
Reviewed-by: Alexandre Blondin Massé <alexandre.blondin.masse@gmail.com>
Reviewed-by: Jean Privat <jean@pryen.org>