doc consequences of f(-->Int:D){Nil}

doc/Language/variables.pod6

@@ -931,6 +931,12 @@ variables :_>.
     my Int $i = 1; # that works
     { use variables :_; my Int $i; } # switch it of in this block
 
+Please note that assigning L<Nil|/type/Nil> will revert the variable to it's
+default value. The default value of a defined constraint type is the type
+appended with C<:D> (e.g. C<Int:D>). That means a definedness contraint is no
+guarantee of definedness. This only applies to variable initializers, not to
+L<Signature|/type/Signature>s. or subsequent assignments to a variable.
+
 =head1 Special Variables
 
 Perl 5 is infamous for its many obscure special variables. Perl 6 also has

doc/Type/Nil.pod6

@@ -48,13 +48,22 @@ C<Nil>.
     say (Nil)[100];                  #-> Nil
     say (Nil){100};                  #-> Nil
 
-When assigned, a C<Nil> evaporates into the type object of the type
-of the container you assigned it into.
+When assigned, C<Nil> will revert a container to it's default value, if no such
+default is provided Perl 6 assumes C<Any>. This includes initializers on
+defined constrained types. Returning C<Nil> from a routine will break the
+definedness constraint. Subsequent assignments to another definedness
+constraint container, including L<Signature|/type/Signature>s, will properly
+fail.
 
     my Int $x = 42;
     $x = Nil;
     $x.say;                     #-> (Int)
 
+    sub f(-->Int:D){Nil};
+    my Int:D $i = f;
+    say $i.defined;
+    # OUTPUT«False␤»
+
 Because an untyped variable is type C<Any>, assigning a C<Nil> to one
 will result in an L<(Any)|/type/Any> type object.