Javadoc fixes

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

build.gradle

@@ -113,6 +113,7 @@ project('spring-statemachine-core') {
 
 configure(sampleProjects()) {
 	apply plugin: 'spring-boot'
+	configurations.archives.artifacts.removeAll { it.archiveTask.is jar }
 	dependencies {
 		compile project(":spring-statemachine-samples-common")
 		testCompile "org.springframework:spring-test:$springVersion"
@@ -123,6 +124,7 @@ configure(sampleProjects()) {
 }
 
 project('spring-statemachine-samples-common') {
+	configurations.archives.artifacts.removeAll { it.archiveTask.is jar }
 	dependencies {
 		compile project(":spring-statemachine-core")
 		compile "org.springframework.shell:spring-shell:1.1.0.RELEASE"
@@ -198,13 +200,21 @@ configure(rootProject) {
 		options.links(
 			'http://docs.jboss.org/jbossas/javadoc/4.0.5/connector'
 		)
-		source subprojects.collect { project ->
+
+		// disable javadocs for samples
+		source subprojects
+		.findAll { project ->
+			!project.name.contains('samples')
+		}
+		.collect { project ->
 			project.sourceSets.main.allJava
 		}
+
 		destinationDir = new File(buildDir, "api")
 		classpath = files(subprojects.collect { project ->
 			project.sourceSets.main.compileClasspath
 		})
+		verbose = true
 		maxMemory = '1024m'
 	}
 
@@ -215,8 +225,12 @@ configure(rootProject) {
 		from('src/dist') {
 			include 'changelog.txt'
 		}
-		from (api) {
-			into 'api'
+		// disable api for jdk8 because we have
+		// some trouble with javadocs
+		if (!JavaVersion.current().isJava8Compatible()) {
+			from (api) {
+				into 'api'
+			}
 		}
 		from (reference) {
 			into 'reference'

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);