diff --git a/main/Defaults.scala b/main/Defaults.scala
index 5485f247e..3da965be1 100644
--- a/main/Defaults.scala
+++ b/main/Defaults.scala
@@ -200,8 +200,6 @@ object Defaults extends BuildCommon
 		mainClass <<= discoveredMainClasses map selectPackageMain,
 		run <<= runTask(fullClasspath, mainClass in run, runner in run),
 		runMain <<= runMainTask(fullClasspath, runner in run),
-		scaladocOptions in GlobalScope :== Nil,
-		scaladocOptions in doc <<= scaladocOptions in doc or scalacOptions.identity,
 		copyResources <<= copyResourcesTask
 	)
 
@@ -430,7 +428,8 @@ object Defaults extends BuildCommon
 
 	def docSetting(key: ScopedTask[File]): Seq[Setting[_]] = inTask(key)(Seq(
 		cacheDirectory ~= (_ / key.key.label),
-		target <<= docDirectory, // deprecate docDirectory in favor of 'target in doc'
+		target <<= docDirectory, // deprecate docDirectory in favor of 'target in doc'; remove when docDirectory is removed
+		scaladocOptions <<= scalacOptions, // deprecate scaladocOptions in favor of 'scalacOptions in doc'; remove when scaladocOptions is removed
 		fullClasspath <<= dependencyClasspath,
 		key in TaskGlobal <<= (sources, cacheDirectory, maxErrors, compilers, target, configuration, scaladocOptions, fullClasspath, streams) map { (srcs, cache, maxE, cs, out, config, options, cp, s) =>
 			(new Scaladoc(maxE, cs.scalac)).cached(cache, nameForSrc(config.name), srcs, cp.files, out, options, s.log)
@@ -438,7 +437,7 @@ object Defaults extends BuildCommon
 		}
 	))
 		
-	@deprecated("Use docSetting", "0.11.0") def docTask: Initialize[Task[File]] =
+	@deprecated("Use `docSetting` instead", "0.11.0") def docTask: Initialize[Task[File]] =
 		(cacheDirectory, compileInputs, streams, docDirectory, configuration, scaladocOptions) map { (cache, in, s, target, config, options) =>
 			val d = new Scaladoc(in.config.maxErrors, in.compilers.scalac)
 			val cp = in.config.classpath.toList - in.config.classesDirectory
diff --git a/main/Keys.scala b/main/Keys.scala
index 26efd5eca..823cf86d1 100644
--- a/main/Keys.scala
+++ b/main/Keys.scala
@@ -102,7 +102,7 @@ object Keys
 
 		// Output paths
 	val classDirectory = SettingKey[File]("class-directory", "Directory for compiled classes and copied resources.")
-	@deprecated("Use 'target', scoped by the doc task.  For example, 'target in Compile in doc'", "0.11.0")
+	@deprecated("Use `target`, scoped by the doc task.  For example, `target in Compile in doc`", "0.11.0")
 	val docDirectory = SettingKey[File]("doc-directory", "Directory for generated documentation.")
 	val cacheDirectory = SettingKey[File]("cache-directory", "Directory used for caching task data.")
 	val cleanFiles = SettingKey[Seq[File]]("clean-files", "The files to recursively delete during a clean.")
@@ -117,6 +117,7 @@ object Keys
 	// compile/doc keys
 	val autoCompilerPlugins = SettingKey[Boolean]("auto-compiler-plugins", "If true, enables automatically generating -Xplugin arguments to the compiler based on the classpath for the " + CompilerPlugin.name + " configuration.")
 	val maxErrors = SettingKey[Int]("max-errors", "The maximum number of errors, such as compile errors, to list.")
+	@deprecated("Use `scalacOptions`, scoped by the doc task.  For example, `scalacOptions in doc`", "0.11.0")
 	val scaladocOptions = TaskKey[Seq[String]]("scaladoc-options", "Options for Scaladoc.")
 	val scalacOptions = TaskKey[Seq[String]]("scalac-options", "Options for the Scala compiler.")
 	val javacOptions = SettingKey[Seq[String]]("javac-options", "Options for the Java compiler.")