Javadoc fixes

- Adding missing javadocs
- Disable javadocs for samples
- Disable api/javadoc for jdk8 which
  we get some internal jdk javadoc errors.
- Fixes #31

spring-statemachine-core/src/main/java/org/springframework/statemachine/config/StateMachineConfigurerAdapter.java

@@ -24,6 +24,14 @@ import org.springframework.statemachine.config.builders.StateMachineTransitionCo
 import org.springframework.statemachine.config.common.annotation.AnnotationBuilder;
 import org.springframework.statemachine.config.common.annotation.ObjectPostProcessor;
 
+/**
+ * Adapter implementation for {@link StateMachineConfigurer}.
+ * 
+ * @author Janne Valkealahti
+ *
+ * @param <S> the type of state
+ * @param <E> the type of event
+ */
 public class StateMachineConfigurerAdapter<S, E> implements StateMachineConfigurer<S, E> {
 
 	private StateMachineTransitionBuilder<S, E> transitionBuilder;

spring-statemachine-core/src/main/java/org/springframework/statemachine/config/StateMachineFactory.java

@@ -17,8 +17,21 @@ package org.springframework.statemachine.config;
 
 import org.springframework.statemachine.StateMachine;
 
+/**
+ * {@code StateMachineFactory} is a strategy interface building {@link StateMachine}s.
+ * 
+ * @author Janne Valkealahti
+ *
+ * @param <S> the type of state
+ * @param <E> the type of event
+ */
 public interface StateMachineFactory<S, E> {
 
+	/**
+	 * Build a new {@link StateMachine} instance.
+	 * 
+	 * @return a new state machine instance.
+	 */
 	StateMachine<S, E> getStateMachine();
 
 }

spring-statemachine-core/src/main/java/org/springframework/statemachine/config/builders/StateMachineConfigurer.java

@@ -18,11 +18,31 @@ package org.springframework.statemachine.config.builders;
 import org.springframework.statemachine.config.StateMachineConfig;
 import org.springframework.statemachine.config.common.annotation.AnnotationConfigurer;
 
+/**
+ * {@link AnnotationConfigurer} exposing configurers for states and transitions.
+ * 
+ * @author Janne Valkealahti
+ *
+ * @param <S> the type of state
+ * @param <E> the type of event
+ */
 public interface StateMachineConfigurer<S, E> extends
 		AnnotationConfigurer<StateMachineConfig<S, E>, StateMachineConfigBuilder<S, E>> {
 
-	void configure(StateMachineStateConfigurer<S, E> transitions) throws Exception;
+	/**
+	 * Callback for {@link StateMachineStateConfigurer}.
+	 * 
+	 * @param states the {@link StateMachineStateConfigurer}
+	 * @throws Exception if configuration error happens
+	 */
+	void configure(StateMachineStateConfigurer<S, E> states) throws Exception;
 
+	/**
+	 * Callback for {@link StateMachineTransitionConfigurer}.
+	 * 
+	 * @param transitions the {@link StateMachineTransitionConfigurer}
+	 * @throws Exception if configuration error happens
+	 */
 	void configure(StateMachineTransitionConfigurer<S, E> transitions) throws Exception;
 
 }

spring-statemachine-core/src/main/java/org/springframework/statemachine/config/builders/StateMachineStateConfigurer.java

@@ -17,8 +17,22 @@ package org.springframework.statemachine.config.builders;
 
 import org.springframework.statemachine.config.configurers.StateConfigurer;
 
+/**
+ * Configurer interface exposing states.
+ * 
+ * @author Janne Valkealahti
+ *
+ * @param <S> the type of state
+ * @param <E> the type of event
+ */
 public interface StateMachineStateConfigurer<S, E> {
 
+	/**
+	 * Gets a configurer for states.
+	 * 
+	 * @return {@link StateConfigurer} for chaining
+	 * @throws Exception if configuration error happens
+	 */
 	StateConfigurer<S, E> withStates() throws Exception;
 
 }

spring-statemachine-core/src/main/java/org/springframework/statemachine/config/builders/StateMachineTransitionConfigurer.java

@@ -19,12 +19,46 @@ import org.springframework.statemachine.config.configurers.ExternalTransitionCon
 import org.springframework.statemachine.config.configurers.InternalTransitionConfigurer;
 import org.springframework.statemachine.config.configurers.LocalTransitionConfigurer;
 
+/**
+ * Configurer interface exposing different type of transitions.
+ * 
+ * @author Janne Valkealahti
+ *
+ * @param <S> the type of state
+ * @param <E> the type of event
+ */
 public interface StateMachineTransitionConfigurer<S, E> {
 
+	/**
+	 * Gets a configurer for external transition. 
+	 * 
+	 * @return {@link ExternalTransitionConfigurer} for chaining
+	 * @throws Exception if configuration error happens
+	 * @see #withLocal()
+	 */
 	ExternalTransitionConfigurer<S, E> withExternal() throws Exception;
 
+	/**
+	 * Gets a configurer for internal transition. Internal transition is used
+	 * when action needs to be executed without causing a state transition. With
+	 * internal transition source and target state is always a same and it is
+	 * identical with self-transition in the absence of state entry and exit
+	 * actions.
+	 * 
+	 * @return {@link InternalTransitionConfigurer} for chaining
+	 * @throws Exception if configuration error happens
+	 */
 	InternalTransitionConfigurer<S, E> withInternal() throws Exception;
 
+	/**
+	 * Gets a configurer for local transition. Local transition doesn’t cause
+	 * exit and entry to source state if target state is a substate of a source
+	 * state. Other way around, local transition doesn’t cause exit and entry to
+	 * target state if target is a superstate of a source state.
+	 * 
+	 * @return {@link LocalTransitionConfigurer} for chaining
+	 * @throws Exception if configuration error happens
+	 */
 	LocalTransitionConfigurer<S, E> withLocal() throws Exception;
 	
 }

spring-statemachine-core/src/main/java/org/springframework/statemachine/config/configuration/StateMachineConfiguration.java

@@ -21,7 +21,6 @@ import java.util.List;
 
 import org.springframework.beans.factory.config.BeanDefinition;
 import org.springframework.beans.factory.support.BeanDefinitionBuilder;
-import org.springframework.beans.factory.support.BeanDefinitionRegistry;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.core.annotation.AnnotationAttributes;
 import org.springframework.core.type.AnnotationMetadata;

spring-statemachine-core/src/main/java/org/springframework/statemachine/config/configurers/TransitionConfigurer.java

@@ -41,16 +41,29 @@ public interface TransitionConfigurer<T, S, E> extends
 	 */
 	T source(S source);
 
+	/**
+	 * Specify a state this transition should belong to.
+	 * 
+	 * @param state the state {@code S}
+	 * @return configurer for chaining
+	 */
 	T state(S state);
 
 	/**
-	 * Specify event {@code E} for this {@link Transition}.
+	 * Specify event {@code E} for this {@link Transition} which will be triggered
+	 * by a event trigger.
 	 *
 	 * @param event the event for transition
 	 * @return configurer for chaining
 	 */
 	T event(E event);
 
+	/**
+	 * Specify that this transition is triggered by a time.
+	 * 
+	 * @param period timer period in millis
+	 * @return configurer for chaining
+	 */
 	T timer(long period);
 
 	/**

spring-statemachine-core/src/main/java/org/springframework/statemachine/processor/MethodAnnotationPostProcessor.java

@@ -37,7 +37,7 @@ public interface MethodAnnotationPostProcessor<T extends Annotation> {
 	 * @param bean the bean
 	 * @param beanName the bean name
 	 * @param method the method
-	 * @param annotation the meta annotation
+	 * @param metaAnnotation the meta annotation
 	 * @param annotation the annotation
 	 * @return the post processed object
 	 */

spring-statemachine-core/src/main/java/org/springframework/statemachine/processor/StateMachineHandler.java

@@ -28,7 +28,6 @@ import org.springframework.statemachine.annotation.WithStateMachine;
  *
  * @author Janne Valkealahti
  *
- * @param <T> the return type
  * @param <S> the type of state
  * @param <E> the type of event
  */

spring-statemachine-core/src/main/java/org/springframework/statemachine/support/tree/TreeTraverser.java

@@ -24,6 +24,9 @@ public abstract class TreeTraverser<T> {
 
 	/**
 	 * Returns the children of the specified node. Must not contain null.
+	 * 
+	 * @param root the node
+	 * @return child iterables
 	 */
 	public abstract Iterable<T> children(T root);