Package com.machinezoo.stagean

This package contains annotation types that can be used to document current development stage on type or member level. Hand-edited annotations can complement the sometimes inaccurate coverage tools. All annotations are visible in javadoc

Four development stages (or levels of quality) are recognized:

  • No* - if that kind of content does not exist at all
  • Stub* - if only short placeholder exists
  • Draft* - if something is unfinished (regardless of how much)
  • Complete* - if that kind of content is finished (default)

The following kinds of content have predefined annotation types:

  • *Api - APIs, i.e. signature and semantics of public types and members
  • *Code - implementation code, i.e. all code behind APIs
  • *Tests - tests, usually unit tests
  • *Docs - javadoc, perhaps also external docs (presumably linked from the javadoc)

There is no NoCode annotation, because it has no meaning and StubCode annotation should be used in its place instead. Applications/libraries are free to define their own annotation types, but the above listed ones are expected to be supported by scanning tools.

Nuances in meaning can be clarified in string parameter that is taken by all annotations. Specific issues are however better described with *Issue annotations, which can be repeated. Longer text can be included in surrounding comments, but to allow tools to display as much information as possible, it is preferable to embed all comments in multi-line string literals using Markdown syntax.

Annotations have retention policy set to RetentionPolicy.RUNTIME. Tools can scan for these annotations in sources, during annotation processing, and in compiled class files. Applications can scan themselves at runtime. Annotations also show up in javadoc for annotated code, so that users are informed about development stage of the class/method they are using.

See Also:
Stagean homepage