The docs could have been more specific about Initialize and Finalize applying to managed variable types only.
For instance the pseudo signature could have been given as:
procedure Initialize( |
var T: TAnyManagedType; |
ACount: SizeInt = 1 |
); |
I support this proposal. I also suggest that you include a link to the documentation page that describes managed types in the description of this procedure. You should also complete the documentation page describing the
Finalize procedure in the same way.
For comparison, I suggest looking at how it is described in the Delphi documentation:
Initialize,
Finalize. The description is a bit better (although it could be more detailed).
Unfortunately, there is also a flaw in the descriptions on these pages. If anyone has looked at the given pages of the Delphi documentation, they will have noticed that the documentation editor made mistakes at the beginning of both pages. Both procedures are overloaded. Identical copies are given in the references, which is misleading to people who do not have enough experience. Is:
procedure Initialize(var V; [ Count: NativeUInt]); overload;
procedure Initialize(var V; [ Count: NativeUInt]); overload;
procedure Finalize(var V; [ Count: NativeUInt]); overload;
procedure Finalize(var V; [ Count: NativeUInt]); overload;
And it should be:
procedure Initialize(var V); overload;
procedure Initialize(var V; [ Count: NativeUInt]); overload;
procedure Finalize(var V); overload;
procedure Finalize(var V; [ Count: NativeUInt]); overload;
On the other hand, inserting a link to a page that contains a list of procedures and functions that support memory management in the description deserves a plus:
Dynamic Memory Allocation Routines.
Such information affects the understanding of the differences between
Initialize and
Default.
The name of the procedure:
Default may also be a problem. It does not reflect well what its purpose is, i.e. fill the variable with zeros (probably even for those who speak English as their native language). Probably a better name for it would be to explicitly call it
Zeroing. But now it probably can't be straightened out (using an alias?).
A page like this in the FPC documentation would be useful. Improving the documentation would greatly help people who are just starting to program in Pascal and Object Pascal using FPC (whether or not they have programmed anything before). I myself once had the understanding of how these subroutines work. Among other things, such trifles significantly affect the popularity of the language. And that's what we care about.