Issue Description:

The documentation for OptionSet reads:

Declare additional preconfigured option set values as static properties initialized with an array literal containing other option values.

The code example shows static properties with arrays of the option values.

The documentation should read something like:

Declare combinations of option values as static properties using the .union() function to combine other option values into larger sets.

and the code example should be:

struct ShippingOptions: OptionSet {
    let rawValue: Int


    static let nextDay    = ShippingOptions(rawValue: 1 << 0)
    static let secondDay  = ShippingOptions(rawValue: 1 << 1)
    static let priority   = ShippingOptions(rawValue: 1 << 2)
    static let standard   = ShippingOptions(rawValue: 1 << 3)


    static let express: ShippingOptions = ShippingOptions.nextDay
                                            .union( ShippingOptions.secondDay)
    static let all: ShippingOptions = ShippingOptions.express
                                            .union(ShippingOptions.priority)
                                            .union(ShippingOptions.standard)
}

Using an array defeats the bitmap because each of the options takes up its own slot in the array. The 'express' ShippingOptions above uses two Ints in storage instead of one, and the all Shipping options uses three Ints.

using .union() sets the bits in the bitmap so all of the options use constant storage (one Int).

It's possible that I am misunderstanding what the documentation says or intends here. If so please let me know. If I do understand this right, I can create a pull request with the new text and send it through. Thanks!