Document describe.one usage

Signed-off-by: James Stocks <jstocks@chef.io>

docs/dsl_inspec.md

@@ -59,7 +59,9 @@ where
 
 ## Advanced concepts
 
-With Chef InSpec it is possible to check if at least one of a collection of checks is true. For example: If a setting is configured in two different locations, you may want to test if either configuration A or configuration B have been set. This is accomplished via `describe.one`. It defines a block of tests with at least one valid check.
+### Checking at least one condition passes with `describe.one`
+
+With Chef InSpec it is possible to check if at least one of a collection of checks is true. For example: If a setting is configured in two different locations, you may want to test if either configuration A or configuration B have been set. This is accomplished via `describe.one`. It defines a set of `describe` blocks, of which only one needs to pass.
 
 ```ruby
 describe.one do
@@ -73,6 +75,12 @@ describe.one do
 end
 ```
 
+#### `describe.one` usage notes
+
+* A `describe.one` block passes if one of its nested `describe` blocks has all assertions passing. That is, it needs an entire `describe` block to pass and not just a single assertion.
+* InSpec will always evaluate all the tests contained within `describe.one`. It does not short-circuit upon evaluating a passing `describe` block.
+* Nesting a `describe.one` block inside another `describe.one` block is not supported.
+
 ### Sensitive resources
 
 In some scenarios, you may be writing checks involving resources with sensitive content (e.g. a file resource). In the case of failures, it may be desired to suppress output. This can be done by adding the `:sensitive` flag to the resource definition
@@ -87,7 +95,7 @@ end
 
 The following examples show simple compliance tests using a single `control` block.
 
-## Test System Event Log
+### Test System Event Log
 
 The following test shows how to audit machines running Windows 2012 R2 that password complexity is enabled:
 
@@ -102,7 +110,7 @@ control 'windows-account-102' do
 end
 ```
 
-## Test if PostgreSQL passwords are empty
+### Test if PostgreSQL passwords are empty
 
 The following test shows how to audit machines running PostgreSQL to ensure that passwords are not empty.
 
@@ -116,7 +124,7 @@ control 'postgres-7' do
 end
 ```
 
-## Test if MySQL passwords are in ENV
+### Test if MySQL passwords are in ENV
 
 The following test shows how to audit machines running MySQL to ensure that passwords are not stored in `ENV`:
 
@@ -134,7 +142,7 @@ control 'mysql-3' do
 end
 ```
 
-## Test if `/etc/ssh` is a Directory
+### Test if `/etc/ssh` is a Directory
 
 The following test shows how to audit machines to ensure that `/etc/ssh` is a directory:
 
@@ -152,7 +160,7 @@ control 'basic-1' do
 end
 ```
 
-## Test if Apache running
+### Test if Apache running
 
 The following test shows how to audit machines to ensure that Apache is enabled and running:
 
@@ -167,7 +175,7 @@ control 'apache-1' do
 end
 ```
 
-## Test if insecure packages are installed
+### Test if insecure packages are installed
 
 The following test shows how to audit machines for insecure packages:
 
@@ -184,7 +192,7 @@ control 'cis-os-services-5.1.3' do
 end
 ```
 
-## Test Windows Registry Keys
+### Test Windows Registry Keys
 
 The following test shows how to audit machines to ensure Safe DLL Search Mode is enabled:
 
@@ -202,7 +210,7 @@ control 'windows-base-101' do
 end
 ```
 
-## Exclude specific test
+### Exclude specific test
 
 This shows how to allow skipping certain tests if conditions are not met, by using `only_if`.
 In this example the test will not be performed if `redis-cli` command does not exist. A optional
@@ -226,7 +234,7 @@ end
 
 Mixing this with other conditionals (like checking existence of the files etc.) can help to test different test paths using InSpec. This way you can skip certain tests which would 100% fail due to the way servers are prepared, but you know that the same test suites are reused later in different circumstances by different teams.
 
-## Additional metadata for controls
+### Additional metadata for controls
 
 The following example illustrates various ways to add tags and references to `control`