Added documentation for disabler objects.

4 files changed, 112 insertions, 0 deletions

diff --git a/docs/markdown/Disabler.md b/docs/markdown/Disabler.md
new file mode 100644
index 000000000..2d50c5cf8
--- /dev/null
+++ b/docs/markdown/Disabler.md
@@ -0,0 +1,65 @@
+---
+short-description: Disabling options
+...
+
+# Disabling parts of the build (available since 0.44.0)
+
+The following is a common fragment found in many projects:
+
+```meson
+dep = dependency('foo')
+
+# In some different directory
+
+lib = shared_library('mylib', 'mylib.c',
+  dependencies : dep)
+
+# And ín a third directory
+
+exe = executable('mytest', 'mytest.c',
+  link_with : lib)
+test('mytest', exe)
+```
+
+This works fine but gets a bit inflexible when you want to make this
+part of the build optional. Basically it reduces to adding `if/else`
+statements around all target invocations. Meson provides a simpler way
+of achieving the same with a disabler object.
+
+A disabler object is created with the `disabler` function:
+
+```meson
+d = disabler()
+```
+
+The only thing you can do to a disabler object is to ask if it has
+been found:
+
+```meson
+f = d.found() # returns false
+```
+
+Any other statement that uses a disabler object will immediately
+return a disabler. For example assuming that `d` contains a disabler
+object then
+
+```meson
+d2 = some_func(d) # value of d2 will be disabler
+d3 = true or d2   # value of d3 will be disabler
+if d              # neither branch is evaluated
+```
+
+Thus to disable every target that depends on the dependency given
+above, you can do something like this:
+
+```meson
+if use_foo_feature
+  d = dependency('foo')
+else
+  d = disabler()
+endif
+```
+
+This concentrates the handling of this option in one place and other
+build definition files do not need to be sprinkled with `if`
+statements.
\ No newline at end of file
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index e6aa9d330..ec5db03d0 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -319,6 +319,10 @@ otherwise. This function supports the following keyword arguments:
 The returned object also has methods that are documented in the
 [object methods section](#dependency-object) below.
 
+### disabler()
+
+Returns a [disabler object]((#disabler-object)). Added in 0.44.0.
+
 ### error()
 
 ``` meson
@@ -1627,6 +1631,15 @@ an external dependency with the following methods:
 
  - `version()` is the version number as a string, for example `1.2.8`
 
+### `disabler` object
+
+A disabler object is an object that behaves in much the same way as
+NaN numbers do in floating point math. That is when used in any
+statement (function call, logical op, etc) they will cause the
+statement evaluation to immediately short circuit to return a disabler
+object. A disabler object has one method:
+
+  - `found()`, always returns `false`
 
 ### `external program` object
 
diff --git a/docs/markdown/snippets/disabler.md b/docs/markdown/snippets/disabler.md
new file mode 100644
index 000000000..1323048cc
--- /dev/null
+++ b/docs/markdown/snippets/disabler.md
@@ -0,0 +1,33 @@
+# Added disabler object
+
+A disabler object is a new kind of object that has very specific
+semantics. If it is used as part of any other operation such as an
+argument to a function call, logical operations etc, it will cause the
+operation to not be evaluated. Instead the return value of said
+operation will also be the disabler object.
+
+For example if you have an setup like this:
+
+```meson
+dep = dependency('foo')
+lib = shared_library('mylib', 'mylib.c',
+  dependencies : dep)
+exe = executable('mytest', 'mytest.c',
+  link_with : lib)
+test('mytest', exe)
+```
+
+If you replace the dependency with a disabler object like this:
+
+```meson
+dep = disabler()
+lib = shared_library('mylib', 'mylib.c',
+  dependencies : dep)
+exe = executable('mytest', 'mytest.c',
+  link_with : lib)
+test('mytest', exe)
+```
+
+Then the shared library, executable and unit test are not
+created. This is a handy mechanism to cut down on the number of `if`
+statements.
diff --git a/docs/sitemap.txt b/docs/sitemap.txt
index 6b155afb7..9c86d60c5 100644
--- a/docs/sitemap.txt
+++ b/docs/sitemap.txt
@@ -26,6 +26,7 @@ index.md
 		Localisation.md
 		Build-options.md
 		Subprojects.md
+		Disabler.md
 		Modules.md
 			Gnome-module.md
 			i18n-module.md