/*
 * Copyright 2014-present Facebook, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.facebook.litho.annotations;

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

/**
 * A method annotated with this annotation is responsible for creating the initial value for
 * params annotated with the {@link State} annotation in this spec. This method will take as
 * parameters a context and an com.facebook.litho.Output for every State variable that it will
 * initialize.
 *
 * <p>For example:
 * <code>
 *
 * {@literal @}LayoutSpec
 * public class MyChangeSetSpec {
 *
 *   {@literal @}OnCreateInitialState
 *   void onCreateInitialState(
 *     ComponentContext c,
 *     Output{@literal <}SomeState{@literal >} someState) {
       someState.set(new SomeState());
 *   }
 * }
 * </code>
 */
@Retention(RetentionPolicy.RUNTIME)
public @interface OnCreateInitialState {

}

@@ -735,107 +735,386 @@
 %0A * 
-A method annotated with this annotation is responsible 
+This annotation is used in a %7B@link LayoutSpec%7D; the framework calls the method annotated with%0A * %7B@code OnCreateInitialState%7D before resolving its layout, i.e. be
 for
+e
  c
-reating the initial value for%0A * params
+alling %7B@link%0A * OnCreateLayout%7D. This lifecycle method should be used to set the initial values of the state of%0A * the component. The annotate method can receive %7B@code StateValue%7D containers for arguments%0A *
  ann
@@ -1125,20 +1125,16 @@
 ed with 
-the 
 %7B@link S
@@ -1142,207 +1142,719 @@
 ate%7D
- annotation 
+.%0A *%0A * %3Cp%3EThe framework can call %7B@code OnCreateInitialState%7D from any thread. The method is invoked%0A * only once dur
 in
+g
  th
-is spec. This method will take as%0A * parameters a context and an com.facebook.litho.Output for every State variable that it will%0A * initialize.%0A *%0A * %3Cp%3EFor example:
+e lifecycle of the Component inside a ComponentTree - when it is first added%0A * to the layout hierarchy. Any updates, such as state updates or prop changes, will not invoke this%0A * method again if its global key did not change. Removing a component and adding it back to the%0A * hierarchy will invoke this method again.%0A *%0A * %3Cp%3E%3Cem%3ERequired:%3C/em%3E%3Cbr%3E%0A *%0A * %3Col%3E%0A *   %3Cli%3E%7B@code ComponentContext%7D%0A * %3C/ol%3E%0A *%0A * %3Cp%3E%3Cem%3EOptional annotated arguments:%3C/em%3E%3Cbr%3E%0A *%0A * %3Cul%3E%0A *   %3Cli%3E%7B@link Prop%7D%0A *   %3Cli%3E%7B@link TreeProp%7D%0A *   %3Cli%3E%7B@link InjectProp%7D%0A *   %3Cli%3E%7B@code StateValue%7D
 %0A * %3C
-code
+/ul
 %3E%0A *%0A * 
 %7B@li
@@ -1849,16 +1849,27 @@
 %3E%0A *%0A * 
+%3Cpre%3E%3Ccode%3E
 %7B@litera
@@ -1871,17 +1871,16 @@
 iteral @
-%7D
 LayoutSp
@@ -1881,16 +1881,17 @@
 youtSpec
+%7D
 %0A * publ
@@ -1903,19 +1903,15 @@
 ass 
-MyChangeSet
+Counter
 Spec
@@ -1918,17 +1918,16 @@
  %7B%0A *%0A *
- 
   %7B@lite
@@ -1931,17 +1931,16 @@
 iteral @
-%7D
 OnCreate
@@ -1951,22 +1951,30 @@
 ialState
+%7D
 %0A *   
+static 
 void onC
@@ -1999,16 +1999,18 @@
 %0A *     
+  
 Componen
@@ -2032,122 +2032,379 @@
     
-Output%7B@literal %3C%7DSomeState%7B@literal %3E%7D someState
+  StateValue&lt;Integer&gt; count) %7B%0A *     count.set(0);%0A *   %7D%0A *%0A *  %7B@literal @OnCreateLayout%7D%0A *   static Component onCreateLayout(%0A *     ComponentContext c,%0A *    %7B@literal @State%7D int count
 ) %7B%0A 
- 
+*%0A *
      
-someState.set(new SomeState(
+return Row.create(c)%0A *       .child(%0A *         Text.create(c)%0A *           .text(String.valueOf(count
 ))
-;
 %0A *   
-%7D%0A *
+    )%0A *       .build();%0A *  
  %7D%0A * 
+%7D
 %3C/code%3E
+%3C/pre%3E
 %0A */
@@ -2480,12 +2480,10 @@
 lState %7B
-%0A%0A
 %7D%0A

Add JavaDoc for OnCreateInitialState