Improved Javadoc for AppState

Here's a version of AppState with improved Javadoc (a patch would have been 
about the same size but harder to read; only comments and a parameter name were 
changed).
I started with the last version posted on 
http://jmonkeyengine.org/forum/topic/simplifying-appstate-transitions/page/6/#po
st-184470 , with a new take on the last open question, threading.

package com.jme3.app.state;

import com.jme3.app.Application;
import com.jme3.renderer.RenderManager;

/**
 * Callbacks for various phases of an {@link Application}’s update loop.<br>
 * The <code>Application</code> creates an {@link AppStateManager} to hold and
 * manage <code>Appstate</code>s.
 * <p>
 * An <code>AppState</code> is always in one of the <i>detached</i>,
 * <i>initializing</i>, <i>running</i>, or <i>terminating</i> states. This state
 * is managed by the associated <code>AppStateManager</code>, which also calls
 * the appropriate {@code AppState} member function exactly once for every
 * status change.<br>
 * <i>Initializing</i> and <i>terminating</i> status are transitory states and
 * are advanced to the next status within the same iteration of the update loop.
 * <p>
 * <b>Notice:</b> The name <code>AppState</code> seems to suggest that all
 * application state should be in subclasses of this interface. However,
 * alternative designs are possible and supported.
 * 
 * @author Kirill Vainer
 */
public interface AppState {

    /**
     * Called by {@link AppStateManager} when transitioning this {@code AppState}
     * from <i>initializing</i> to <i>running</i>.<br>
     * This will happen on the next iteration through the update loop after
     * {@link AppStateManager#attach()} was called.
     * <p>
     * <code>AppStateManager</code> will call this only from the update loop
     * inside the rendering thread.<br>
     * In a standard-practices JME application where only the
     * <code>AppStateManager</code> calls this function from the render loop, this
     * means is it safe to modify the scene graph from this function.
     * 
     * @param stateManager The state manager
     * @param app The application
     */
    public void initialize(AppStateManager stateManager, Application app);

    /**
     * @return True if <code>initialize()</code> was called on this
     *         <code>AppState</code>, false otherwise.
     */
    public boolean isInitialized();

    /**
     * Enable or disable the functionality of this <code>AppState</code>.<br>
     * A disabled <code>AppState</code>s does not get calls to
     * {@link #update(float)}, {@link #render(RenderManager)}, or
     * {@link #postRender()} from its {@link AppStateManager}.
     * 
     * @param enable New {@link #isEnabled()} state for the AppState.
     */
    public void setEnabled(boolean enable);

    /**
     * @return True if the <code>AppState</code> is enabled, false otherwise.
     * 
     * @see AppState#setEnabled(boolean)
     */
    public boolean isEnabled();

    /**
     * Called by {@link AppStateManager#attach()} when transitioning this
     * <code>AppState</code> from <i>detached</i> to <i>initializing</i>.
     * <p>
     * JME makes no assumptions about the thread from which this function is
     * called.<br>
     * In a standard-practices JME application, this means that it is
     * <b>unsafe</b> to modify the scene graph from this function.
     * 
     * @param stateManager State manager to which the state was attached to.
     */
    public void stateAttached(AppStateManager stateManager);

    /**
     * Called by {@link AppStateManager#detach()} when transitioning this
     * <code>AppState</code> from <i>running</i> to <i>terminating</i>.
     * <p>
     * JME makes no assumptions about the thread from which this function is
     * called.<br>
     * In a standard-practices JME application, this means that it is
     * <b>unsafe</b> to modify the scene graph from this function.
     * 
     * @param stateManager The state manager from which the state was detached from.
     */
    public void stateDetached(AppStateManager stateManager);

    /**
     * Adjust this <code>AppState</code> for the passage of time since the last
     * update cycle.
     * <p>
     * {@link AppStateManager} calls this once per iteration through the update
     * loop, before calling the {@link #render()} function of any
     * <code>AppState</code>.<br>
     * The call does not happen if this <code>AppState</code> is not enabled.
     * <p>
     * <code>AppStateManager</code> will call this only from the update loop
     * inside the rendering thread.<br>
     * In a standard-practices JME application where only the
     * <code>AppStateManager</code> calls this function from the render loop, this
     * means is it safe to modify the scene graph from this function.
     * 
     * @param tpf Time since the last call to update(), in fractional seconds.
     */
    public void update(float tpf);

    /**
     * Render this <code>AppState</code>’s state using <code>rm</code>.
     * <p>
     * {@link AppStateManager} calls this once per iteration through the update
     * loop.<br>
     * The call does not happen if this <code>AppState</code> is not enabled.
     * <p>
     * <code>AppStateManager</code> will call this only from the update loop
     * inside the rendering thread.<br>
     * In a standard-practices JME application where only the
     * <code>AppStateManager</code> calls this function from the render loop, this
     * means is it safe to modify the scene graph from this function.
     * 
     * @param rm RenderManager
     */
    public void render(RenderManager rm);

    /**
     * Do any cleanup that needs to be postponed after all other
     * <code>AppState</code>s have had their calls to <code>render</code>.<br>
     * (Delaying cleanup in this way is rarely a necessity.)
     * <p>
     * {@link AppStateManager} calls this once per iteration through the update
     * loop.<br>
     * The call does not happen if this <code>AppState</code> is not enabled.
     * <p>
     * <code>AppStateManager</code> will call this only from the update loop
     * inside the rendering thread.<br>
     * In a standard-practices JME application where only the
     * <code>AppStateManager</code> calls this function from the render loop, this
     * means is it safe to modify the scene graph from this function.
     */
    public void postRender();

    /**
     * Called by {@link AppStateManager} when transitioning this
     * <code>AppState</code> from <i>terminating</i> to <i>detached</i>.<br>
     * This will happen on the next iteration through the update loop after
     * {@link AppStateManager#detach()} was called.
     * <p>
     * <code>AppStateManager</code> will call this only from the update loop
     * inside the rendering thread.<br>
     * In a standard-practices JME application where only the
     * <code>AppStateManager</code> calls this function from the render loop, this
     * means is it safe to modify the scene graph from this function.
     */
    public void cleanup();

}
Original issue reported on code.google.com by toolfor...@gmail.com on 30 Mar 2013 at 3:40
zghib / jmonkeyengine

Improved Javadoc for AppState #589
