DATACASS-388 - Improve JavaDoc for configuration classes.

spring-cql/src/main/java/org/springframework/cassandra/config/java/AbstractClusterConfiguration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2013-2016 the original author or authors.
+ * Copyright 2013-2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -51,6 +51,16 @@ import com.datastax.driver.core.policies.SpeculativeExecutionPolicy;
 @Configuration
 public abstract class AbstractClusterConfiguration {
 
+	/**
+	 * Creates a {@link CassandraCqlClusterFactoryBean} that provides a Cassandra
+	 * {@link com.datastax.driver.core.Cluster}. The lifecycle of {@link CassandraCqlClusterFactoryBean} executes
+	 * {@link #getStartupScripts() startup} and {@link #getShutdownScripts() shutdown} scripts.
+	 *
+	 * @return the {@link CassandraCqlClusterFactoryBean}.
+	 * @see #cluster()
+	 * @see #getStartupScripts()
+	 * @see #getShutdownScripts()
+	 */
 	@Bean
 	public CassandraCqlClusterFactoryBean cluster() {
 

spring-cql/src/main/java/org/springframework/cassandra/config/java/AbstractCqlTemplateConfiguration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 the original author or authors.
+ * Copyright 2016-2017 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,6 +23,7 @@ import org.springframework.context.annotation.Bean;
  * and {@link com.datastax.driver.core.Cluster} creation. This class is usually extended by user configuration classes.
  *
  * @author Matthew T. Adams
+ * @author Mark Paluch
  * @see org.springframework.cassandra.config.java.AbstractClusterConfiguration
  * @see org.springframework.cassandra.config.java.AbstractSessionConfiguration
  * @see com.datastax.driver.core.Session
@@ -31,8 +32,14 @@ import org.springframework.context.annotation.Bean;
  */
 public abstract class AbstractCqlTemplateConfiguration extends AbstractSessionConfiguration {
 
+	/**
+	 * Creates a {@link CqlTemplate} configured with {@link #session()}.
+	 * 
+	 * @return the {@link CqlTemplate}.
+	 * @see #session()
+	 */
 	@Bean
-	public CqlTemplate cqlTemplate() throws Exception {
+	public CqlTemplate cqlTemplate() {
 		return new CqlTemplate(session().getObject());
 	}
 }

spring-cql/src/main/java/org/springframework/cassandra/config/java/AbstractSessionConfiguration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2013-2014 the original author or authors.
+ * Copyright 2013-2017 the original author or authors.
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,21 +21,28 @@ import org.springframework.context.annotation.Configuration;
 
 /**
  * Spring {@link @Configuration} class used to configure a Cassandra client application
- * {@link com.datastax.driver.core.Session} connected to a Cassandra {@link com.datastax.driver.core.Cluster}.
- *
- * Enables a Cassandra Keyspace to be specified along with the ability to execute arbitrary CQL on startup
- * as well as shutdown.
+ * {@link com.datastax.driver.core.Session} connected to a Cassandra {@link com.datastax.driver.core.Cluster}. Enables a
+ * Cassandra Keyspace to be specified along with the ability to execute arbitrary CQL on startup as well as shutdown.
  *
  * @author Matthew T. Adams
  * @author John Blum
+ * @author Mark Paluch
  * @see org.springframework.cassandra.config.java.AbstractClusterConfiguration
  * @see org.springframework.context.annotation.Configuration
  */
 @Configuration
 public abstract class AbstractSessionConfiguration extends AbstractClusterConfiguration {
 
+	/**
+	 * Creates a {@link CassandraCqlSessionFactoryBean} that provides a Cassandra
+	 * {@link com.datastax.driver.core.Session}.
+	 *
+	 * @return the {@link CassandraCqlSessionFactoryBean}.
+	 * @see #cluster()
+	 * @see #getKeyspaceName()
+	 */
 	@Bean
-	public CassandraCqlSessionFactoryBean session() throws Exception {
+	public CassandraCqlSessionFactoryBean session() {
 
 		CassandraCqlSessionFactoryBean bean = new CassandraCqlSessionFactoryBean();
 
@@ -45,6 +52,11 @@ public abstract class AbstractSessionConfiguration extends AbstractClusterConfig
 		return bean;
 	}
 
+	/**
+	 * Return the name of the keyspace to connect to.
+	 *
+	 * @return must not be {@literal null}.
+	 */
 	protected abstract String getKeyspaceName();
 
 }

spring-data-cassandra/src/main/java/org/springframework/data/cassandra/config/java/AbstractCassandraConfiguration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2013-2016 the original author or authors
+ * Copyright 2013-2017 the original author or authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -50,6 +50,21 @@ public abstract class AbstractCassandraConfiguration extends AbstractClusterConf
 
 	protected ClassLoader beanClassLoader;
 
+	/**
+	 * Creates a {@link CassandraSessionFactoryBean} that provides a Cassandra {@link com.datastax.driver.core.Session}.
+	 * The lifecycle of {@link CassandraSessionFactoryBean} initializes the {@link #getSchemaAction() schema} in the
+	 * {@link #getKeyspaceName() configured keyspace}.
+	 * 
+	 * @return the {@link CassandraSessionFactoryBean}.
+	 * @throws ClassNotFoundException if an error occurs initializing the initial entity set, see
+	 *           {@link #cassandraMapping()}
+	 * @see #cluster()
+	 * @see #cassandraConverter()
+	 * @see #getKeyspaceName()
+	 * @see #getSchemaAction()
+	 * @see #getStartupScripts()
+	 * @see #getShutdownScripts()
+	 */
 	@Bean
 	public CassandraSessionFactoryBean session() throws ClassNotFoundException {
 
@@ -66,11 +81,12 @@ public abstract class AbstractCassandraConfiguration extends AbstractClusterConf
 	}
 
 	/**
-	 * Creates a {@link CassandraConverter} using the configured {@link #cassandraMapping()}.
-	 * Will apply all specified {@link #customConversions()}.
+	 * Creates a {@link CassandraConverter} using the configured {@link #cassandraMapping()}. Will apply all specified
+	 * {@link #customConversions()}.
 	 *
 	 * @return {@link CassandraConverter} used to convert Java and Cassandra value types during the mapping process.
-	 * @throws Exception if an error occurs initializing or registering the converter.
+	 * @throws ClassNotFoundException if an error occurs initializing the initial entity set, see
+	 *           {@link #cassandraMapping()}
 	 * @see #cassandraMapping()
 	 * @see #customConversions()
 	 */
@@ -100,8 +116,8 @@ public abstract class AbstractCassandraConfiguration extends AbstractClusterConf
 	/**
 	 * Return the {@link MappingContext} instance to map Entities to properties.
 	 *
-	 * @throws ClassNotFoundException if the Cassandra Entity class type identified by name
-	 * cannot be found during the scan.
+	 * @throws ClassNotFoundException if the Cassandra Entity class type identified by name cannot be found during the
+	 *           scan.
 	 * @see CassandraMappingContext
 	 */
 	@Bean
@@ -138,7 +154,7 @@ public abstract class AbstractCassandraConfiguration extends AbstractClusterConf
 
 	/**
 	 * Base packages to scan for entities annotated with {@link Table} annotations. By default, returns the package name
-	 * of {@literal this} (<code>this.getClass().getPackage().getName()</code>). This method must never return null.
+	 * of {@literal this} ({@code this.getClass().getPackage().getName()}. This method must never return {@literal null}.
 	 */
 	public String[] getEntityBasePackages() {
 		return new String[] { getClass().getPackage().getName() };

src/main/asciidoc/reference/cassandra.adoc

@@ -678,7 +678,7 @@ These entity classes can be used to create Cassandra table specifications and us
 Schema creation is tied to `Session` initialization with `SchemaAction`. Following actions are supported:
 
 * `SchemaAction.NONE`: No tables/types will be created or dropped. This is the default setting.
-* `SchemaAction.CREATE`: Create tables and user-defined types from entities annotated with `@Table and types annotated with `@UserDefinedType`. Existing tables/types will cause an error if the type is attempted to be created.
+* `SchemaAction.CREATE`: Create tables and user-defined types from entities annotated with `@Table` and types annotated with `@UserDefinedType`. Existing tables/types will cause an error if the type is attempted to be created.
 * `SchemaAction.CREATE_IF_NOT_EXISTS`: Like `SchemaAction.CREATE` but with `IF NOT EXISTS` applied. Existing tables/types won't cause any errors but may remain stale.
 * `SchemaAction.RECREATE`: Drops and recreate existing tables and types that are known to be used. Tables and types that are not configured in the application are not dropped.
 * `SchemaAction.RECREATE_DROP_UNUSED`: Drop all tables and types and recreate only known tables and types.