package arez.annotations;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;
import javax.annotation.Nonnull;

/**
 * Methods marked with this annotation are converted to autoruns.
 * Autorun methods are invoked by the Arez runtime and should never be invoked directly by user code.
 *
 * <p>The method that is annotated with @Autorun must comply with the additional constraints:</p>
 * <ul>
 * <li>Must not be annotated with any other arez annotation</li>
 * <li>Must not be private</li>
 * <li>Must not be public</li>
 * <li>Must not be static</li>
 * <li>Must not be final</li>
 * <li>Must not be abstract</li>
 * </ul>
 */
@Documented
@Target( ElementType.METHOD )
public @interface Autorun
{
  /**
   * Return the name of the Autorun relative to the component.
   * 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 ArezComponent} annotated element.
   *
   * @return the name of the Autorun relative to the component.
   */
  @Nonnull
  String name() default "<default>";

  /**
   * Does the autorun mutate state or not.
   * The default value us false thus making the transaction mode read-only. The intention is that autorun observers
   * should primarily be reflecting Arez state to external systems. (i.e. views, network layers etc.)
   *
   * @return true if the autorun should run in a READ_WRITE transaction, false if it should run in a READ_ONLY transaction.
   */
  boolean mutation() default false;

  /**
   * The priority of the underlying autorun observer
   *
   * @return the priority of the autorun observer.
   */
  Priority priority() default Priority.NORMAL;

  /**
   * Flag controlling whether the underlying observer can observe ComputedValue instances with lower priorities.
   * The default value of false will result in an invariant failure (in development mode) if a lower priority
   * dependency is observed by the observer. This is to prevent priority inversion when scheduling a higher
   * priority observer is dependent upon a lower priority computed value. If the value is true then the no
   * invariant failure is triggered and the component relies on the component author to handle possible priority
   * inversion.
   *
   * @return false if observing lower priority dependencies should result in invariant failure in development mode.
   */
  boolean observeLowerPriorityDependencies() default false;

  /**
   * Flag controlling whether the observer can invoke actions.
   * An action that specifies {@link Action#requireNewTransaction()} as true will start a new transaction
   * and any observables accessed within the action will not be dependencies of the observer. Sometimes this
   * behaviour is desired. Sometimes an action that specifies {@link Action#requireNewTransaction()} as false
   * will be used instead and any observable accessed within the scope of the action will be a dependency of
   * the observer and thus changes in the observable will reschedule the observer. Sometimes this
   * behaviour is desired. Either way the developer must be conscious of these decisions and thus must explicitly
   * set this flag to true to invoke any actions within the scope of the observers reaction.
   *
   * @return true if the observer can invoke actions, false otherwise.
   */
  boolean nestedActionsAllowed() default false;
}

@@ -783,39 +783,40 @@
 the name of the 
-Autorun
+Observer
  relative to the
@@ -1106,23 +1106,24 @@
  of the 
-Autorun
+Observer
  relativ
@@ -1221,164 +1221,79 @@
 the 
-autorun mutate state or not.%0A   * The default value us false thus making the transaction mode read-only. The intention is that autorun observers%0A   * should
+observer's tracking method change arez state or not.%0A   * Observers are
  pri
@@ -1303,18 +1303,23 @@
 ily 
-be
+used to
  reflect
 ing 
@@ -1314,19 +1314,16 @@
  reflect
-ing
  Arez st
@@ -1326,16 +1326,18 @@
 z state 
+on
 to exter
@@ -1347,17 +1347,16 @@
  systems
-.
  (i.e. v
@@ -1390,68 +1390,151 @@
    *
-%0A   * @return true if the autorun should run in a READ_WRITE
+ and thus the default value is false thus making the transaction mode read-only.%0A   *%0A   * @return true if the observer should use a read-write
  tra
@@ -1566,26 +1566,23 @@
 uld 
-run in a READ_ONLY
+use a read-only
  tra
@@ -1676,24 +1676,16 @@
 erlying 
-autorun 
 observer
@@ -1727,16 +1727,8 @@
 the 
-autorun 
 obse
@@ -1823,35 +1823,24 @@
 whether the 
-underlying 
 observer can
@@ -2136,16 +2136,21 @@
 bserver 
+that 
 is depen
@@ -2557,32 +2557,11 @@
   * 
-Flag controlling whether
+Can
  the
@@ -2562,36 +2562,32 @@
 an the observer 
-can 
 invoke actions.%0A

Improve the language in javadocs