package org.realityforge.arez.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Methods marked with this annotation are observable values within Arez.
 *
 * <p>The method should only invoked within the scope of a transaction.</p>
 */
@Retention( RetentionPolicy.RUNTIME )
@Target( ElementType.METHOD )
public @interface Observable
{
  /**
   * Return the name of the Observable relative to the container.
   * The value must conform to the requirements of a java identifier.
   * The name must also be unique across {@link Observable}s,
   * {@link Computed}s and {@link Action}s within the scope of the
   * {@link Container} annotated element.
   *
   * @return the name of the Observable relative to the container.
   */
  String name() default "<default>";
}

@@ -210,156 +210,1156 @@
 %0A * 
-Methods marked with this annotation are observable values within Arez.%0A *%0A * %3Cp%3EThe method should only invoked within the scope of a transaction.%3C/p
+Annotation applied to methods that expose an Observable value in Arez.%0A * Methods annotated with this either query state or mutate state. The query%0A * method is expected to have 0 parameters and return a value and by default%0A * is named with %22get%22 or %22is%22 prefixed to the property name. The mutation%0A * method is expected to have a single parameter and return no value and by%0A * default is named with %22set%22 prefixed to property name. The setter or getter%0A * can also be named matching the property name without the prefix.%0A *%0A * %3Cp%3EOnly one of the query or mutation method needs to be annotated with%0A * this annotation if the other method follows the normal conventions. If%0A * the other method does not conform to conventions, then you will need to%0A * annotate the pair and specify a value for %7B@link #name()%7D.%3C/p%3E%0A *%0A * %3Cp%3EThe method should only invoked within the scope of a transaction.%0A * The mutation method requires that the transaction be READ_WRITE.%3C/p%3E%0A *%0A * %3Cp%3EThe method that is annotated with @Observable must also comply with the following constraints:%3C/p%3E%0A * %3Cul%3E%0A * %3Cli%3EMust not be final%3C/li%3E%0A * %3Cli%3EMust not be abstract%3C/li%3E%0A * %3C/ul
 %3E%0A *
@@ -1526,24 +1526,121 @@
 e container.
+ If not specified%0A   * will default to the name of the property by convention as described above.
 %0A   * The va

Document the additional requirements on @Observable annotated elements