Contradiction in Documentation?!?!?

[Zvoni]

Hi Folks,
stumbled across this one:
https://www.freepascal.org/docs-html/current/ref/refse61.html#x120-1440009.1

Some of the restrictions when compared to classes or objects are obvious from the syntax diagram:

    No inheritance of records.
    No published and protected section exists.
    Constructors or destructors cannot be defined.
    Class methods (if one can name them so) require the static keyword.
    Methods cannot be virtual or abstract – this is a consequence of the fact that there is no inheritance.

Further down at the examples:

TTest4 = record 
 private 
   a : Integer; 
 protected 
   function getp : integer; 
 public 
   b : string; 
   procedure setp (aValue : integer); 
   property p : integer read Getp Write SetP; 
 public 
 case x : integer of 
   1 : (Q : string[10]); 
   2 : (S : String[10]); 
 end;

Huh???

[VisualLab]

I made a small test with the code provided in the documentation (I supplemented it with the content of the methods). An attempt to compile such a test ends with the compiler message:

unit1.pas(38,3) Error: Visibility section "PROTECTED" not allowed in records

Code: Pascal  [Select][+][-]

1. unit Unit1;
2.  
3. {$mode objfpc}{$H+}
4. {$modeswitch advancedrecords}
5. //{$mode Delphi}{$H+}
6.  
7. interface
8.  
9. uses
10.   Classes, SysUtils, Forms, Controls, Graphics, Dialogs;
11.  
12. type
13.   TTest1 = record
14.     A: Integer;
15.     function Test(ARecurse: Boolean): Integer;
16.   end;
17.  
18.   TTest2 = record
19.   private
20.     FA, FB: Integer;
21.   public
22.     procedure SetA(AValue : Integer);
23.     property SafeA: Integer read FA write SetA;
24.   end;
25.  
26.   TTest3 = packed record
27.   private
28.     FA, FB: Byte;
29.     function GetA: Integer;
30.     procedure SetA(AValue: Integer);
31.   public
32.     property A: Integer read GetA write SetA;
33.   end;
34.  
35.   TTest4 = record
36.   private
37.     FA: Integer;
38.   protected
39.     function GetP: Integer;
40.   public
41.     B: string;
42.     procedure SetP(AValue: Integer);
43.     property P: Integer read GetP write SetP;
44.   public
45.   case X: Integer of
46.     1: (Q: string[10]);
47.     2: (S: String[10]);
48.   end;
49.  
50.   TForm1 = class(TForm)
51.   private
52.  
53.   public
54.  
55.   end;
56.  
57. var
58.   Form1: TForm1;
59.  
60. implementation
61.  
62. {$R *.lfm}
63.  
64. function TTest1.Test(ARecurse: Boolean): Integer;
65. begin
66.   Result := 0;
67.   if ARecurse
68.    then Result := A;
69. end;
70.  
71. procedure TTest2.SetA(AValue : Integer);
72. begin
73.   if FA <> AValue
74.    then FA := AValue;
75. end;
76.  
77. function TTest3.GetA: Integer;
78. begin
79.   Result := FA;
80. end;
81.  
82. procedure TTest3.SetA(AValue: Integer);
83. begin
84.   if FA <> AValue
85.    then FA := AValue;
86. end;
87.  
88. function TTest4.GetP: Integer;
89. begin
90.   Result := FA;
91. end;
92.  
93. procedure TTest4.SetP(AValue: Integer);
94. begin
95.   if FA <> AValue
96.    then FA := AValue;
97. end;
98.  
99. end.

The compiler reports this for both modes: Delphi and ObjFPC. You can see it in the attachment.

[VisualLab]

While we're on the subject of FPC documentation, I found this on 6.6.5 Class constructors and destructors website:

There are some caveats when using class destructors/constructors:

• There may be only one constructor per class. The name is arbitrary, but it can not have parameters.
• There may be only one destructor per class. The name is arbitrary, but it can not have parameters.
• Neither constructor nor destructor can be virtual.
• The class constructor/destructor is called irrespective of the use of the class: even if a class is never used, the constructor and destructor are called anyway.

But after reviewing a few FCL or LCL library files, it is immediately obvious that:

• There can be many constructors and they can be overloaded (which is quite common),
• The constructor can have parameters (arguments) and any number of them (i.e. none, 1 or more),
• Constructors and destructors can be virtual, of course one parameterless (i.e.: without any arguments) destructor per class,
• Is it true that a class constructor/destructor is called independently of the class usage (even if the class is never used)? And if only class methods are used (i.e.: class procedure), then what? Why would a class instance be created then?

Note: This is not documentation on object constructors and destructors. That is provided at 5.5 Constructors and destructors .

Maybe I missed something, or didn't understand something. Or the editing of this part of the documentation was not finished and is incomplete.

[AlexTP]

Maybe report both issues to the https://gitlab.com/freepascal.org/fpc/documentation/-/issues ?

[Zvoni]

Maybe report both issues to the https://gitlab.com/freepascal.org/fpc/documentation/-/issues ?

Will do tomorrow, at least my own

EDIT: https://gitlab.com/freepascal.org/fpc/documentation/-/issues/39412

[tetrastes]

While we're on the subject of FPC documentation, I found this on 6.6.5 Class constructors and destructors website:

This is about class constructors and destructors. They are for the whole class, like class methods. You confuse them with "usual" constructors and destructors for class instances.

Code: Pascal  [Select][+][-]

1. {$mode objfpc}  
2. {$h+}  
3.  
4. Type  
5.   TA = Class(TObject)  
6.   Private  
7.     Function GetA : Integer;  
8.     Procedure SetA(AValue : integer);  
9.  
10.   public  
11.     Class Constructor create;  
12.     Class Destructor destroy;  
13.     Property A : Integer Read GetA Write SetA;  
14.   end;

Note Class before Constructor and Destructor.

[Thaddy]

Yup, all others are wrong. Documentation for class constructor and methods is correct.
And that should have been obvious, since https://www.freepascal.org/docs-html/ref/refsu29.html contains an example.
Reading is an art....

[VisualLab]

While we're on the subject of FPC documentation, I found this on 6.6.5 Class constructors and destructors website:

This is about class constructors and destructors. They are for the whole class, like class methods. You confuse them with "usual" constructors and destructors for class instances.

Yes, you are right that I misunderstood the content. I was surprised that the word class is given before the keywords constructor and destructor. And I assumed (wrongly) that the content of this page was not fully edited. The example provided (copied from the aforementioned WWW page) does not contribute anything, because it is not described (i.e. what is what and why).

Yup, all others are wrong. Documentation for class constructor and methods is correct.

Yes, you are right, the documentation is correct

And that should have been obvious, since https://www.freepascal.org/docs-html/ref/refsu29.html contains an example.

Yes, I agree. This should be obvious. But it isn't. Guess why? Because the documentation is incomplete! In fact, it is rudimentary. It does not contain any important information. The example provided is also not very helpful, because it is not described (what is what, why and for what). And above all, there is no clear statement that it is not about constructors and destructors of class instances, but about constructors and destructors of classes as types. That they are used to initialize the class itself and not the class instance and that they are used very rarely. Those people who did not know (or do not know) what this "documentation" is about, did not understand (will not understand) anything based on it (e.g. me). Imagine that documentation is (usually) written for such people who do not yet have specific knowledge. And they are the ones who need it. Those who already know do not need documentation (since they know). The actual documentation about class constructors and destructors is here:

Delphi constructor and class constructor (Stack Overflow)

and here:

Class Constructors
Class Destructors

This is real documentation. Not some miserable mentions, without specifics. Because "the devil is in the details".

Reading is an art....

Writing is an even greater art. In particular, writing in such a way that the content is understandable and describes the topic in sufficient detail. Unfortunately, from time to time on the FPC and Lazarus documentation pages you come across such "seeds" of real documentation. This certainly does not bring Pascal (and Lazarus) new users.

[Thaddy]

Yes, you are right 

[n7800]

I always like documentation that explicitly provides a footnote like "This is a description of ABC. Not to be confused with ABCD." for similar terms. This saves a lot of time for users when learning, and for developers, who won't get a lot of unnecessary questions.

I think the problem starts with the table of contents, where the good name is specified for class constructors/destructors, and the page for "regular" constructors/destructors has a completely unremarkable name "Class instantiation". It should definitely be the other way around.

Classes are a very important part of the language, and the help for them should be as clear as possible. Since no one has created an issue on the bug tracker, I took it upon myself. Feel free to add clarifications and specific suggestions there.

https://gitlab.com/freepascal.org/fpc/documentation/-/issues/39415


IMHO, there would be no confusion if the word "static" was used instead of "class"... It's a pity that this can't be changed.

[Thaddy]

I think that very, very few people do make the mistake of mixing up methods/constructors with class methods/constructors. Very, very few, otherwise this would have come up a very long time ago.
Personally I don't see any reason to adapt the documentation.
I can't even find a similar entry on the forum and class methods are over 25 years old.
What makes it even more sad that someone filed a bug report over this issue.
Plz think three times before you file a bug report.

[n7800]

Unfortunately, very few people will write about the error. Surely, people on the forum/bug tracker are less than 0.01% of FPC/Lazarus users. To write a report, you need to:
* Be sure that this is an error. But if you read the documentation, you are most likely not sure.
* Find feedback (a specific forum or bug tracker).
* Register on the site.
* Write about a error, preferably providing links with evidence or program examples. And do it in English.

Moreover, at this time people are most likely busy writing their program, and they have neither time nor interest in correcting the documentation.

As a result, they will simply silently find another source. But most likely, they will not get to this documentation site at all, but will look for articles with usage examples on other sites written in their native language.

On bug trackers (both documentation and code) you can find enough problems that talk about errors that appeared a long time ago. I have done error bisection many times, going far back into old versions. And I don't believe that no one noticed it - no one just wrote about it.


By the way, just to be clear - I created a report not to fix the error (since there is none, if you read it carefully), but about improving the documentation, which will help to avoid misunderstandings and save people time.

Just look at the titles of the three pages (see content) with the topics being discussed, it's impossible not to confuse them:

Code: Pascal  [Select][+][-]

1. Class instantiation
2. Class destruction
3. Class constructors and destructors

The page "Class destruction" has only a three-character difference, so as not to be called "Class destructor" and not to indicate a different kind of destructor...