doc.go

// Package annogo provides runtime support for Go annotations. This package is
// referenced from code generated by aptgo, for providing runtime access to
// annotation values that are intended to be runtime-visible.
//
// The various Register* functions should not be called directly, but instead
// only called from generated code. The other functions can then be used to
// inspect runtime-visible annotation values (which were registered from said
// generated code during package initialization).
//
// It also provides the foundational meta-annotations, which Go developers use
// to define their own annotations.
//
// Annotation Syntax
//
// Annotations on constructs in Go source code take the form of
// specially-formatted comments. At the end of normal Go doc, add annotations
// by writing annotation values, starting with an at sign ("@") in front of
// each annotation type (similar to annotation syntax in Java). Any comment line
// that starts with such an at sign is assumed by annotation processors to be
// the first line of annotations, and all comment lines following it are also
// assumed to be part of the annotations.
//
// So, for packages with annotations (e.g. those on which you might run the
// aptgo tool or other processing tools), it is important that no Go doc for any
// element have a line that starts with the at sign ("@") unless that line is
// the start of the doc'ed element's annotations.
//
// Like a statement in the Go language, an annotation should be all on a single
// line or break lines after characters that do not break expressions (such as
// open braces, open parentheses, binary operators, commas, etc).
//
//   // An annotation on a single line
//   // @annogo.Annotation{AllowedElements: Types}
//
//   // An annotation that spans multiple lines
//   // @annogo.Annotation{
//   //     AllowedElements: Types, // not trailing comma, like in other Go code
//   // }
//
// Multiple annotations go on multiple lines, though they can all be crammed on
// a single line if they are separated with semicolons (again, like normal
// statements in the Go language).
//
//   // Multiple annotations on multiple lines
//   // @annogo.Required
//   // @annogo.DefaultValue(123)
//
//   // Or multiple annotations on a single line
//   // @annogo.Required; @annogo.DefaultValue(123)
//
// As seen in the examples above, a single annotation starts with the at sign
// ("@") followed by the name of the annotation type, including a package
// qualifier.
//
//   // @annogo.Annotation
//
// With just the annotation name, the annotation's value is its zero value with
// one important exception: if the annotation type is a struct and it has any
// field with a @annogo.DefaultValue annotation, that field will have the
// specified default value (not the field's zero value).
//
// If the annotation type is a struct and has any fields with a @annogo.Required
// annotation, values *must* be indicated in the annotation, so this syntax
// (annotation type without a value) will not be allowed.
//
// Annotations that indicate values can use one of two syntaxes:
//   1. If the annotation type is a scalar, the value must be in parenthesis,
//      just like a type conversion expression in normal Go code.
//   2. If the annotation type is a composite type (struct, array, slice, or
//      map), the values are in curly braces, just like the syntax for composite
//      literals in normal Go code.
//
//   // Scalar value
//   @pkg.IntegerAnnotation(123)
//   // Composite value
//   @pkg.SliceAnnotation{123, 456, 789}
//
// There are two exceptions to these rules:
//   1. If the annotation type is a struct with a single field names "Value"
//      then the value can be written as if it were a scalar, and the scalar
//      value will be promoted to a struct with that its singular field value.
//   2. If the annotation type is a slice of scalar values or an array of
//      length one, then the value can be written as if it were a scalar, and it
//      will be promoted to a single-element slice or array.
// These promotions are syntactic sugar to make annotation values more concise.
//
// The first case, an annotation type that is a struct with a single field named
// "Value", is useful when using annotations that only allow annotation fields
// as the kind of annotated element. If the annotation type were defined as a
// scalar type, the value of that scalar type could not have this sort of
// annotation on it (since they would be on a type element, not a field). So you
// can work around this by instead declaring the annotation as a single-field
// struct and then apply the annotations to the one field.
//
//   // Example annotations
//   // @annogo.Annotation
//   type SimpleAnno struct {
//       // @annogo.DefaultValue("foobar")
//       Value string
//   }
//   // @annogo.Annotation
//   type SliceAnno []string
//
//   // Uses of these annotations may use scalar syntax:
//   // @SimpleAnno("frobnitz")
//   // @SliceAnno("abc")
//
//   // The above annotations are equivalent to these:
//   // @SimpleAnno{Value: "frobnitz"}
//   // @SliceAnno{"abc"} // subtle: braces instead of parentheses
//
// Annotation Expressions
//
// The syntax of annotation values is the same as the syntax for constant
// expressions in normal Go code with a few additions:
//   1. Annotation expressions may use composite literals (slices, arrays, maps,
//      and structs).
//   2. Annotation expressions may use literal nils. They can be used to express
//      typed nils, too, but not for channel or interface types, only for slice,
//      map, function, and pointer types.
//   2. Annotation expressions may refer to top-level functions by name, not
//      just to constants. This includes qualified names of methods of top-level
//      named types and interfaces.
//   3. While composite literals can be typed (e.g. include explicit type), the
//      types can be omitted in most cases: type are inferred based on the known
//      structure of the expression's type. For example, with a struct literal,
//      the types of the struct's fields are known, so it is not necessary to
//      state them in the annotation expression.
//
// Channel values cannot be expressed with annotation expressions other than via
// untyped literal nils.
//
// Expressions in annotation values do not support pointer operations such as
// pointer-dereference (*) or address-of (&). However, pointer types are allowed
// and operations, such as address-of, are handled transparently.
//
//   // Here's an annotation with a pointer field
//   // @annogo.Annotation
//   type MyAnno struct {
//       PtrField *int
//   }
//
//   // Here's how we use it:
//   // @MyAnno{PtrField: 123}
//   var SomeAnnotatedElement int
//   // When reified (during processing or at runtime, for runtime-visible
//   // annotations), the value will be a pointer, and the pointed-to value will
//   // be 123. As mentioned, the address-of (&) operator has been applied
//   // transparently.
//
// Like in constant expressions in normal Go code, function calls are disallowed
// except for a few special builtin functions for manipulating complex values:
// imag(c), real(c), and complex(fr, fi).
//
// Annotations and Element Types
//
// TODO
//
// Meta-Annotations
//
// This package contains some meta-annotations, including the one that defines
// all other annotations: @annogo.Annotation. A meta-annotation is an
// annotation that is used only on other annotations (or their fields). They
// are used to define characteristics of other annotations.
//
// In addition to to @annogo.Annotation, there are some other meta-annotations
// in this package worth knowing about:
//
//  * @annogo.Required: This annotation is used on fields of annotation structs
//    and indicates that the annotated field will not use a zero or default
//    value. It is required that uses of the annotation provide a value for the
//    field.
//  * @annogo.DefaultValue: This annotation is used on fields of annotation
//    structs and indicates the default value to use for the field when a use of
//    annotation does not provide a value. Typically, default values, just like
//    in normal Go code, will zero values of their respective types. But this
//    annotation provides a way to indicate non-zero values as defaults. It is
//    an error to annotate a field with both the Required and DefaultValue
//    annotations -- if it has an explicit default, it makes no sense to also be
//    required.
//
// Runtime-Visible Annotations
//
// Querying annotation values at runtime (for annotations that are visible at
// runtime) is done using functions in this package, too. (There are numerous
// Register* functions, which record the annotation values during package
// initialization. But these should only be used by the code that is generated
// by the aptgo tool.)
//
// The other functions take three shapes:
//   1. GetAnnotationsFor*: These functions return annotations of a given type
//      for a particular element. There is one function for each kind of
//      annotated element, and each has its own way for calling code to identify
//      the element.
//   2. GetAllAnnotationsFor*: These functions are similar to the previous set
//      but do not take an annotation type. Instead, they return all annotations
//      on a given element, for all annotation types.
//   3. GetAnnotated*OfType: These functions are for querying vars and consts of
//      a given type that have annotations. This is most useful for types that
//      are effectively enums, as it provides a way to query for all of the
//      consts (presumably the enum values). However, it only returns elements
//      that have annotations.
//
package annogo