Clarify nilable type syntax regarding unions

[jstoiko]

Closes #708

[BlockLucas]

Hi!

Before in 1.0 there wasn’t any definition for this nilable sugar for references, just a comment in an example (here) for a scalar & a definition for properties (here).
For us is not a PATCH change.

To discuss a little further on this, as we previously talked a little in raml-org/raml-tck#138 with
this example:

types:
  TypeWithTrailing?:
    type: string
  TypeWithTrailing:
    type: int
  TestObject:
    type: object
    properties:
      prop: TypeWithTrailing?

If "prop" should reference type "TypeWithTrailing" (int), marking it as nilable.
How we should behave in cases like these:

types:
  TypeWithTrailing?:
    type: string
  TestObject:
    type: object
    properties:
      notnilable: TypeWithTrailing?

Under that logic, this should fail (because "TypeWithTrailing" doesn't exists), but "TypeWithTrailing?" becomes unreachable or unusable for this sugar

[jstoiko]

This was an obvious omission. This has also been extensively discussed before (see #569, #665).

To answer your question Re: what happens when a type name contains a trailing question mark, I think the referencing mechanism should first look at types with that name before inferring that it means | nil. The Property Declarations has an example of a "double question mark" key. Maybe we can add one for values too.

[dukesphere]

suggests avoiding use of terms like "in lieu of" and Latin abbreviations so that it is understood by a wider audience