SizeInt documentation

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

SizeInt documentation

Jürgen Hestermann
The documenation in

http://www.freepascal.org/docs-html/rtl/system/sizeint.html

says:
-----------------------

SizeInt

Signed integer type which fits for sizes

Declaration

Source position: systemh.inc line 251

type SizeInt = LongInt;

-----------------------

which seems to be wrong. In Systemh.inc it is declared

-----------------------
{$ifdef CPU64}
  SizeInt = Int64;
{$endif CPU64}

{$ifdef CPU32}
  SizeInt = Longint;
{$endif CPU32}

{$ifdef CPU16}
  SizeInt = Integer;
{$endif CPU16}
-----------------------

but the documentation says that it is always Longint.
Can someone please correct this as it causes a lot of confusion.


_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: SizeInt documentation

leledumbo
Administrator
> but the documentation says that it is always Longint.
> Can someone please correct this as it causes a lot of confusion.

fpdoc parser understands and interprets compiler directives, so it can't display something that's defined differently for each platform. As you can see, we have *nix units documented online/downloadable but the others don't. The description can be used to explain further, but the source cannot.

example:
http://www.freepascal.org/docs-html/rtl/system/ptruint.html

the source still displays 32-bitism (= DWord), but the description says bitness neutral explanation ("size of a pointer" is CPU dependent).
Reply | Threaded
Open this post in threaded view
|

Re: *** GMX Spamverdacht *** Re: SizeInt documentation

Jürgen Hestermann
Am 2015-06-21 um 16:25 schrieb leledumbo:
but the documentation says that it is always Longint.
Can someone please correct this as it causes a lot of confusion.
fpdoc parser understands and interprets compiler directives, so it can't
display something that's defined differently for each platform. 
Then something is wrong with how the documentation is "generated" (shouldn't it be written by a human?).
A documenation of a type that has different meanings on different platforms should tell about this.
That's what a documentation is for!


As you can see, we have *nix units documented online/downloadable but the others don't.
How should I know that these documentations are for *nix only?
They don't say this anywhere.


The description can be used to explain further, but the source cannot.
example:
http://www.freepascal.org/docs-html/rtl/system/ptruint.html
the source still displays 32-bitism (= DWord), but the description says
bitness neutral explanation ("size of a pointer" is CPU dependent).
That is totally missleading and makes the "documentation" useless.
It does not inform about all side effects which IMO is the purpose
of a documentation. Otherwise I can also guess (and try).
I would expect that the "source" part is manually written in the same
way as the "description" part.
What is the use of writing contradicting statements like these into a documentation:

"Unsigned integer type with same size as Pointer."
and
"type
PtrUInt = DWord;
"

What size is PtrUInt? The same as a pointer or DWord?
They differ on 64 bit systems.

Keep in mind that the documentation is for those people
who do *NOT* know (for sure) what these types mean.
All others would not read it anyway.


_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: *** GMX Spamverdacht *** Re: SizeInt documentation

leledumbo
Administrator
> Then something is wrong with how the documentation is "generated" (shouldn't it be written by a human?).

In these automatic documentation generator days? I don't think so.

> A documenation of a type that has different meanings on different platforms should tell about this.
> That's what a documentation is for!

Well, the user guide, programmer's reference or basically everything other than the API documentation mentions whenever something is platform specific. And they're hand written.

> How should I know that these documentations are for *nix only?

*nix units are not available on non-nix platforms, it's that simple.

> That is totally missleading and makes the "documentation" useless.
> It does not inform about all side effects which IMO is the purpose
> of a documentation. Otherwise I can also guess (and try).
> I would expect that the "source" part is manually written in the same
> way as the "description" part.

Going back to everything manual is NOT a solution (How many places must be modified when an API changes? How do you ensure the documentation and source be consistent?), find something else possible and feasible. If you want to hack fpdoc parser to include all possible definitions, by all means go ahead and send the patches. Do something like what doxygen does: http://www.stack.nl/~dimitri/doxygen/manual/preprocessing.html where the directive processing is controllable by a switch. I have no idea how hard is that, AFAIK it uses fcl-passrc which is a generic Object Pascal (as understood by FPC) parser. That could be your starting point.

FYI, you can generate the documentations yourself, so it will be specific to your platform.
Reply | Threaded
Open this post in threaded view
|

Re: *** GMX Spamverdacht *** Re: *** GMX Spamverdacht *** Re: SizeInt documentation

Jürgen Hestermann
Am 2015-06-21 um 20:16 schrieb leledumbo:
 >> A documenation of a type that has different meanings on different
 >> platforms should tell about this.
 >> That's what a documentation is for!
 > Well, the user guide, programmer's reference or basically everything other
 > than the API documentation mentions whenever something is platform specific.
 > And they're hand written.

Then I don't understand what the web page
http://www.freepascal.org/docs-html/rtl/system/sizeint.html
realy is.
I thought it was an online documentation of the Free Pascal runtime library.
Is it not?
What is the API documentation you talk about?
Free Pascal cannot be documented without the OS-specific details.
Isn't the SIZEINT type a part of Free Pascal?
Then a documentation has to tell all details about it.
Otherwise it cannot be called documentation.
But what is then?


 >> How should I know that these documentations are for *nix only?
 > *nix units are not available on non-nix platforms, it's that simple.

When I search for "sizeint" in google I find
http://www.freepascal.org/docs-html/rtl/system/sizeint.html
What is unix-related here?
It is a general documentation of the SIZEINT type.
Not a single word about *nix.


 > Going back to everything manual is NOT a solution (How many places must be
 > modified when an API changes? How do you ensure the documentation and source
 > be consistent?),

How is this ensured in the programmer's reference?

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: SizeInt documentation

Michael Van Canneyt
In reply to this post by Jürgen Hestermann


On Mon, 22 Jun 2015, Jürgen Hestermann wrote:

> Am 2015-06-21 um 20:16 schrieb leledumbo:
>>> A documenation of a type that has different meanings on different
>>> platforms should tell about this.
>>> That's what a documentation is for!
>> Well, the user guide, programmer's reference or basically everything other
>> than the API documentation mentions whenever something is platform
> specific.
>> And they're hand written.
>
> Then I don't understand what the web page
> http://www.freepascal.org/docs-html/rtl/system/sizeint.html
> realy is.
> I thought it was an online documentation of the Free Pascal runtime library.
> Is it not?
> What is the API documentation you talk about?
> Free Pascal cannot be documented without the OS-specific details.
> Isn't the SIZEINT type a part of Free Pascal?
> Then a documentation has to tell all details about it.
> Otherwise it cannot be called documentation.
> But what is then?
>
>
>>> How should I know that these documentations are for *nix only?
>> *nix units are not available on non-nix platforms, it's that simple.
>
> When I search for "sizeint" in google I find
> http://www.freepascal.org/docs-html/rtl/system/sizeint.html
> What is unix-related here?
> It is a general documentation of the SIZEINT type.
> Not a single word about *nix.
SizeInt has nothing to do with the OS, everything with the CPU.

I have improved the documentation of SizeInt, it will be visible in the next release.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal