Documentation confusion or error

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

Documentation confusion or error

Graeme Geldenhuys-6
Hi,

https://www.freepascal.org/docs-html/rtl/sysutils/longrec.html

I'm referring to the documentation shown in the URL above. As far as I
know the fpdoc is sensitive to which platform it is running on (unless
explicitly told otherwise), and will generate documentation according to
that platform. Please correct me if I am wrong, but this was my personal
experience with fpdoc.

Anyway, as far as I know the FPC documentation is normally generated on
a Linux system with 64-bit Intel type CPU.

If so, that means the documentation shown above has the Hi, Lo fields in
the wrong order. Showing Big Endian instead of Little Endian (what Intel
desktop CPU's are).


Based on the real source code found in sysutilh.inc, this is how the
record is actually defined:


   LongRec = packed record
      case Integer of
{$ifdef FPC_LITTLE_ENDIAN}
        0 : (Lo,Hi : Word);
{$else FPC_LITTLE_ENDIAN}
        0 : (Hi,Lo : Word);
{$endif FPC_LITTLE_ENDIAN}
        1 : (Bytes : Array[0..3] of Byte);
   end;

It seems that when generating documentation the FPC_LITTLE_ENDIAN
compiler define is not specified, thus fpdoc defaults to using and
showing the Big Endian source code.


On a side note:
  It might also be a good idea to indicate inside the documentation
  which system was used to generate the docs. Maybe the footer or some
  "About -> Notations" page. As far as I know fpdoc can't show
  documentation for multiple platforms together (like the source code
  shown above).


Regards,
  Graeme

--
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/

My public PGP key:  http://tinyurl.com/graeme-pgp
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation confusion or error

Michael Van Canneyt


On Wed, 8 May 2019, Graeme Geldenhuys wrote:

> Hi,
>
> https://www.freepascal.org/docs-html/rtl/sysutils/longrec.html
>
> I'm referring to the documentation shown in the URL above. As far as I
> know the fpdoc is sensitive to which platform it is running on (unless
> explicitly told otherwise), and will generate documentation according to
> that platform. Please correct me if I am wrong, but this was my personal
> experience with fpdoc.
>
> Anyway, as far as I know the FPC documentation is normally generated on
> a Linux system with 64-bit Intel type CPU.
>
> If so, that means the documentation shown above has the Hi, Lo fields in
> the wrong order. Showing Big Endian instead of Little Endian (what Intel
> desktop CPU's are).

The defines need to be added to the fpdoc command-line.
I will add FPC_LITTLE_ENDIAN to the list of defines.

Can you please create a bugreport so I will not forget ?

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

Re: Documentation confusion or error

Graeme Geldenhuys-6
On 08/05/2019 12:58 pm, Michael Van Canneyt wrote:
> Can you please create a bugreport so I will not forget ?

No problem.

   https://bugs.freepascal.org/view.php?id=35542


Regards,
  Graeme

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