From d3dcef7efc1df3b7a645eb6dc75c4a66a9131cb9 Mon Sep 17 00:00:00 2001
From: Jussi Pakkanen <jpakkane@gmail.com>
Date: Sat, 2 Dec 2017 22:17:21 +0200
Subject: Added documentation for disabler objects.

---
 docs/markdown/snippets/disabler.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 docs/markdown/snippets/disabler.md

(limited to 'docs/markdown/snippets')

diff --git a/docs/markdown/snippets/disabler.md b/docs/markdown/snippets/disabler.md
new file mode 100644
index 0000000..1323048
--- /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.
-- 
cgit v1.1