Clarify when BUILD applies default values to attributes

[schultzdavid]

https://docs.raku.org/language/objects#Object_construction

The current phrasing ("All attributes that have not been touched in any of the previous steps") is ambiguous, since "any" might be understood as including all runs of the parent classes' bless method. Thus, change wording to "not been touched in the previous two steps". The added remark "(overriding any parent attributes of the same name)" makes this even more explicit.

I'm a bit on the fence about the wording "override" though, since the parent class itself retains its attribute intact; the child class's attribute merely "eclipses" it:

class Shape  {
  has $.scale = 10;
  submethod BUILD(:$param) {
    $!scale = $param;
  }
}

class Line is Shape {
  has $.scale;
}
my $l = Line.new( param => 0.5);
say $l;
say $l.scale;
say $l.Shape::scale;

# OUTPUT:
Line.new(scale => Any, scale => 0.5)
(Any)
0.5

[coke]

'm a bit on the fence about the wording "override" though, since the parent class itself retains its attribute intact

So maybe just be explicit and say “in this sub class”?

[schultzdavid]

I think now that the best solution is to add a new bullet point to the list of "Implications" right below, between what are currently the second and third bullet points (i.e. between the ones that begin with "Custom BUILD methods should always..." and "BUILD may set an attribute, but...").

In this new point one can then say explicitly that parent attributes are not exactly overwritten, rather being still accessible per :: syntax and by parent's method.

In addition, as the very first of all the bullet points of the section, one should probably add one that mentions the declaration and initialization of attributes declared by the child class (which takes place before BUILD and before applying default values, and which is the actual cause of the eclipsing of parent attributes with the same name):

class Parent { has $.x = 5; has $.y; has @.a= [1,2,3] }
class Child is Parent { 
  has $.x; has $.y = 10; has @.a = [1]; 
  submethod BUILD(){ say self.x; say self.y; say self.a; } 
}
say my $c = Child.new;  
# (Any)  # c.x initialized, already eclipsing parent's $.x
# (Any)  # c.y initialized; default value of 10 not yet applied
# []     # c.a initialized; default value of [1] not yet applied
# Child.new(x => Any, y => 10, a => [1], x => 5, y => Any, a => [1, 2, 3])
say $c.x;  # (Any)
say $c.y;  # 10
say $c.a;  # [1]

This is all essentially specced in roast S12-methods/accessors.t lines 54–69.

I'll see to write something soon-ish.