Skip to content

Commit c76cf4d

Browse files
committed
Improve struct constructor docs, add subsections
Move 'Union Constructors' section before struct ctors, rather than in the middle of it. Fix ctor Parameters and ParameterList links. Move 2 general paragraphs for copy constructor to end of the main section (as subsections are more specific). Add link to copy constructors from legacy postblit section.
1 parent 9d3eae9 commit c76cf4d

File tree

2 files changed

+51
-34
lines changed

2 files changed

+51
-34
lines changed

spec/class.dd

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -335,7 +335,7 @@ $(GNAME Constructor):
335335
called.)
336336

337337
$(P Constructors are defined with a function name of $(D this)
338-
and having no return value:)
338+
and have no return value:)
339339

340340
------
341341
class Foo

spec/struct.dd

Lines changed: 50 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -379,6 +379,12 @@ $(H2 $(LEGACY_LNAME2 ConstStruct, const-struct, Const, Immutable and Shared Stru
379379
----
380380
)
381381

382+
383+
$(H2 $(LNAME2 UnionConstructor, Union Constructors))
384+
385+
$(P Unions are constructed in the same way as structs.)
386+
387+
382388
$(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors))
383389

384390
$(P Struct constructors are used to initialize an instance of a struct when a more
@@ -387,15 +393,15 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
387393
$(LINK2 #struct-literal, struct literal).
388394
)
389395

390-
$(P Constructors are defined with a function name of `this` and having no return value.
396+
$(P Constructors are defined with a function name of `this` and have no return value.
391397
The grammar is the same as for the class $(GLINK2 class, Constructor).
392398
)
393399

394400
$(P A struct constructor is called by the name of the struct followed by
395-
$(GLINK2 class, Parameters).
396-
$(P If the $(GLINK2 class, ParameterList) is empty,
397-
the struct instance is default initialized.)
401+
$(GLINK2 function, Parameters).
398402
)
403+
$(P If the $(GLINK2 function, ParameterList) is empty,
404+
the struct instance is default initialized.)
399405

400406
$(SPEC_RUNNABLE_EXAMPLE_FAIL
401407
---
@@ -412,7 +418,7 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
412418
void main()
413419
{
414420
S a = S(4, 5); // calls S.this(4, 5): a.x = 4, a.y = 5, a.z = 6
415-
S b = S(); // default initialized: a.x = 0, b.y = 4, b.y = 6
421+
S b = S(); // default initialized: b.x = 0, b.y = 4, b.z = 6
416422
S c = S(1); // error, matching this(int) not found
417423
}
418424
---
@@ -431,9 +437,11 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
431437
---
432438
)
433439

434-
$(P Constructors can call other constructors for the same struct
435-
in order to share common initializations
436-
(this is called a $(DDSUBLINK spec/class, delegating-constructors, delegating constructor)):
440+
$(H3 $(LNAME2 delegating-constructor, Delegating Constructors))
441+
442+
$(P A constructor can call another constructor for the same struct
443+
in order to share common initializations. This is called a
444+
$(I delegating constructor):
437445
)
438446

439447
$(SPEC_RUNNABLE_EXAMPLE_FAIL
@@ -458,12 +466,12 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
458466
---
459467
)
460468

461-
$(P The following restrictions apply to struct construction:)
469+
$(P The following restrictions apply:)
462470

463471
$(OL
464-
$(LI If a constructor's code contains a delegate constructor call, all
472+
$(LI If a constructor's code contains a delegating constructor call, all
465473
possible execution paths through the constructor must make exactly one
466-
delegate constructor call:
474+
delegating constructor call:
467475

468476
$(SPEC_RUNNABLE_EXAMPLE_FAIL
469477
---
@@ -494,14 +502,18 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
494502
)
495503

496504
$(LI It is illegal to refer to $(D this) implicitly or explicitly
497-
prior to making a delegate constructor call.)
505+
prior to making a delegating constructor call.)
498506

499-
$(LI Once the delegate constructor returns, all fields are considered
507+
$(LI Once the delegating constructor returns, all fields are considered
500508
constructed.)
501509

502-
$(LI Delegate constructor calls cannot appear after labels.)
510+
$(LI Delegating constructor calls cannot appear after labels.)
503511
)
504512

513+
$(P See also: $(DDSUBLINK spec/class, delegating-constructors, delegating class constructors).)
514+
515+
516+
$(H3 $(LNAME2 struct-instantiation, Struct Instantiation))
505517

506518
$(P When an instance of a struct is created, the following steps happen:)
507519

@@ -522,6 +534,8 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
522534
)
523535

524536

537+
$(H3 $(LNAME2 constructor-attributes, Constructor Attributes))
538+
525539
$(P A constructor qualifier (`const`, `immutable` or `shared`) constructs the object instance
526540
with that specific qualifier.
527541
)
@@ -583,6 +597,8 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
583597
---
584598
)
585599

600+
$(H4 $(LNAME2 pure-constructors, Pure Constructors))
601+
586602
$(P If the constructor can create a unique object (i.e. if it is `pure`),
587603
the object is implicitly convertible to any qualifiers.
588604
)
@@ -611,9 +627,9 @@ $(H2 $(LEGACY_LNAME2 Struct-Constructor, struct-constructor, Struct Constructors
611627

612628

613629

614-
$(H2 $(LNAME2 disable_default_construction, Disabling Default Struct Construction))
630+
$(H3 $(LNAME2 disable_default_construction, Disabling Default Struct Construction))
615631

616-
$(P If struct constructor is annotated with $(D @disable) and has
632+
$(P If a struct constructor is annotated with $(D @disable) and has
617633
an empty $(GLINK2 function, ParameterList), the struct has disabled default construction.
618634
The only way it can be constructed is via a call to another constructor with a non-empty
619635
$(I ParameterList).
@@ -624,7 +640,7 @@ $(H2 $(LNAME2 disable_default_construction, Disabling Default Struct Constructio
624640

625641
$(P A disabled default constructor may not have a $(GLINK2 function, FunctionBody).)
626642

627-
$(P If any fields have disabled default construction, the struct default construction is
643+
$(P If any fields have disabled default construction, struct default construction is
628644
also disabled.)
629645

630646
$(SPEC_RUNNABLE_EXAMPLE_FAIL
@@ -661,20 +677,15 @@ $(H2 $(LNAME2 disable_default_construction, Disabling Default Struct Constructio
661677
such as `null`, is not acceptable.)
662678

663679

664-
$(H2 $(LNAME2 UnionConstructor, Union Constructors))
665-
666-
$(P Unions are constructed in the same way as structs.)
680+
$(H3 $(LNAME2 field-init, Field initialization inside a constructor))
667681

668-
669-
$(H2 $(LNAME2 field-init, Field initialization inside constructor))
670-
671-
$(P In a constructor body, if a delegate constructor is called,
682+
$(P In a constructor body, if a delegating constructor is called,
672683
all field assignments are considered assignments.
673684
Otherwise, the first instance of field assignment is
674685
its initialization, and assignments of the form `field = expression`
675686
are treated as equivalent to `typeof(field)(expression)`.
676687
The values of fields may be read before initialization or construction
677-
with a delegate constructor.
688+
with a delegating constructor.
678689
)
679690

680691
$(SPEC_RUNNABLE_EXAMPLE_COMPILE
@@ -810,7 +821,7 @@ $(H2 $(LNAME2 field-init, Field initialization inside constructor))
810821
---
811822
)
812823

813-
$(H2 $(LEGACY_LNAME2 StructCopyConstructor, struct-copy-constructor, Struct Copy Constructors))
824+
$(H3 $(LEGACY_LNAME2 StructCopyConstructor, struct-copy-constructor, Struct Copy Constructors))
814825

815826
$(P Copy constructors are used to initialize a `struct` instance from
816827
another `struct` of the same type.)
@@ -910,6 +921,14 @@ $(H2 $(LEGACY_LNAME2 StructCopyConstructor, struct-copy-constructor, Struct Copy
910921
}
911922
---
912923

924+
$(P If a `union S` has fields that define a copy constructor, whenever an object of type `S`
925+
is initialized by copy, an error will be issued. The same rule applies to overlapped fields
926+
(anonymous unions).)
927+
928+
$(P A `struct` that defines a copy constructor is not a POD.)
929+
930+
$(H4 $(LNAME2 copy-constructor-attributes, Copy Constructor Attributes))
931+
913932
$(P The copy constructor can be overloaded with different qualifiers applied
914933
to the parameter (copying from a qualified source) or to the copy constructor
915934
itself (copying to a qualified destination):
@@ -957,6 +976,8 @@ $(H2 $(LEGACY_LNAME2 StructCopyConstructor, struct-copy-constructor, Struct Copy
957976
}
958977
---
959978

979+
$(H4 $(LNAME2 implicit-copy-constructors, Implicit Copy Constructors))
980+
960981
$(P A copy constructor is generated implicitly by the compiler for a `struct S`
961982
if all of the following conditions are met:)
962983

@@ -977,11 +998,6 @@ $(H2 $(LEGACY_LNAME2 StructCopyConstructor, struct-copy-constructor, Struct Copy
977998

978999
$(P If the generated copy constructor fails to type check, it will receive the `@disable` attribute.)
9791000

980-
$(P If a `union S` has fields that define a copy constructor, whenever an object of type `S`
981-
is initialized by copy, an error will be issued. The same rule applies to overlapped fields
982-
(anonymous unions).)
983-
984-
$(P A `struct` that defines a copy constructor is not a POD.)
9851001

9861002
$(H2 $(LEGACY_LNAME2 StructPostblit, struct-postblit, Struct Postblits))
9871003

@@ -991,8 +1007,9 @@ $(GNAME Postblit):
9911007
$(D this $(LPAREN) this $(RPAREN)) $(GLINK2 function, MemberFunctionAttributes)$(OPT) $(GLINK2 function, FunctionBody)
9921008
)
9931009

994-
$(P WARNING: The postblit is considered legacy and is not recommended for new code. Code should use copy
995-
constructors defined in the previous section. For backward compatibility reasons, a `struct` that defines
1010+
$(P WARNING: The postblit is considered legacy and is not recommended for new code.
1011+
Code should use $(RELATIVE_LINK2 struct-copy-constructor, copy constructors)
1012+
defined in the previous section. For backward compatibility reasons, a `struct` that defines
9961013
both a copy constructor and a postblit will only use the postblit for implicit copying.)
9971014

9981015
$(P $(I Copy construction) is defined as initializing

0 commit comments

Comments
 (0)