Re: [fpc-pascal] *** 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  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] *** GMX Spamverdacht *** Re: SizeInt documentation

[leledumbo]

> 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.



--
View this message in context: 
http://free-pascal-general.1045716.n5.nabble.com/SizeInt-documentation-tp5721877p5721889.html
Sent from the Free Pascal - General mailing list archive at Nabble.com.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal