luke
/
sbt
mirror of https://github.com/sbt/sbt.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1846 from sschaef/improve-plugins-doc 

Fixes #1845. Reformat Scaladoc of `AutoPlugin`
This commit is contained in:
Josh Suereth 2015-02-17 22:07:39 -05:00
parent dba47afd9e 9a51264c96
commit a17dd3de74
1 changed files with 49 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
main/src/main/scala/sbt/Plugins.scala
View File

@ -12,43 +12,49 @@ import Plugins._
import annotation.tailrec import annotation.tailrec
/** /**
An AutoPlugin defines a group of settings and the conditions where the settings are automatically added to a build (called "activation"). * An AutoPlugin defines a group of settings and the conditions where the settings are automatically added to a build (called "activation").
The `requires` and `trigger` methods together define the conditions, and a method like `projectSettings` defines the settings to add. * The `requires` and `trigger` methods together define the conditions, and a method like `projectSettings` defines the settings to add.
*
Steps for plugin authors: * Steps for plugin authors:
1. Determine if the AutoPlugin should automatically be activated when all requirements are met, or should be opt-in. *
2. Determine the [[AutoPlugins]]s that, when present (or absent), act as the requirements for the AutoPlugin. * 1. Determine if the `AutoPlugin` should automatically be activated when all requirements are met, or should be opt-in.
3. Determine the settings/configurations to that the AutoPlugin injects when activated. * 1. Determine the `AutoPlugin`s that, when present (or absent), act as the requirements for the `AutoPlugin`.
4. Determine the keys and other names to be automatically imported to *.sbt scripts. * 1. Determine the settings/configurations to that the `AutoPlugin` injects when activated.
* 1. Determine the keys and other names to be automatically imported to `*.sbt` scripts.
For example, the following will automatically add the settings in `projectSettings` *
to a project that has both the `Web` and `Javascript` plugins enabled. * For example, the following will automatically add the settings in `projectSettings`
* to a project that has both the `Web` and `Javascript` plugins enabled.
object Plugin extends sbt.AutoPlugin { *
override def requires = Web && Javascript * {{{
override def trigger = allRequirements * object MyPlugin extends sbt.AutoPlugin {
override def projectSettings = Seq(...) * override def requires = Web && Javascript
* override def trigger = allRequirements
object autoImport { * override def projectSettings = Seq(...)
lazy val obfuscate = taskKey[Seq[File]]("Obfuscates the source.") *
} * object autoImport {
} * lazy val obfuscate = taskKey[Seq[File]]("Obfuscates the source.")
* }
Steps for users: * }
1. Add dependencies on plugins in `project/plugins.sbt` as usual with `addSbtPlugin` * }}}
2. Add key plugins to Projects, which will automatically select the plugin + dependent plugin settings to add for those Projects. *
3. Exclude plugins, if desired. * Steps for users:
*
For example, given plugins Web and Javascript (perhaps provided by plugins added with addSbtPlugin), * 1. Add dependencies on plugins in `project/plugins.sbt` as usual with `addSbtPlugin`
* 1. Add key plugins to projects, which will automatically select the plugin + dependent plugin settings to add for those projects.
<Project>.enablePlugins( Web && Javascript ) * 1. Exclude plugins, if desired.
*
will activate `MyPlugin` defined above and have its settings automatically added. If the user instead defines * For example, given plugins Web and Javascript (perhaps provided by plugins added with `addSbtPlugin`),
*
<Project>.enablePlugins( Web && Javascript ).disablePlugins(MyPlugin) * {{{
* myProject.enablePlugins(Web && Javascript)
then the `MyPlugin` settings (and anything that activates only when `MyPlugin` is activated) will not be added. * }}}
*
* will activate `MyPlugin` defined above and have its settings automatically added. If the user instead defines
* {{{
* myProject.enablePlugins(Web && Javascript).disablePlugins(MyPlugin)
* }}}
*
* then the `MyPlugin` settings (and anything that activates only when `MyPlugin` is activated) will not be added.
*/ */
abstract class AutoPlugin extends Plugins.Basic with PluginsFunctions { abstract class AutoPlugin extends Plugins.Basic with PluginsFunctions {
/** Determines whether this AutoPlugin will be activated for this project when the `requires` clause is satisfied. /** Determines whether this AutoPlugin will be activated for this project when the `requires` clause is satisfied.
@ -238,9 +244,8 @@ ${listConflicts(conflicting)}""")
override def toString = "<none>" override def toString = "<none>"
} }
/** An included or excluded Nature/Plugin. TODO: better name than Basic. Also, can we dump /** An included or excluded Nature/Plugin. */
* this class. // TODO: better name than Basic. Also, can we dump this class
*/
sealed abstract class Basic extends Plugins { sealed abstract class Basic extends Plugins {
def &&(o: Basic): Plugins = And(this :: o :: Nil) def &&(o: Basic): Plugins = And(this :: o :: Nil)
} }