[fpc-devel] Makeskel errors on Windows

[Hans-Peter Diettrich]

Michael Van Canneyt schrieb:

>> At least TSystemTime is declared there, used in GetLocalTime (Win32 
>> platform). Dunno about other types or constants, used in other Win32 
>> RTL and FCL units (winsocks...).
> 
> If you'd check carefully TSystemTime is declared and documented in 
> sysutils.

Not in the windows version.

> If you build for Win32, then it's not documented, because on windows, 
> the windows unit definition is used. It's one of the reasons why I 
> explicitly build for Linux:
> the RTL contains many structures that have their roots in the win32 API.
> On other platforms, these structures are defined explicitly outside the 
> windows unit, and hence, documented.
> 
> So it seems to me you created an artificial problem.

Why me? It's fpdoc who chooses to ignore the description :-(

I only revealed several inconsistencies with the generation of the RTL
documentation on a Windows system. Currently it looks as if it is a bad
idea to generate the documentation in a platform-dependent way at all.

AFAIR the mess started with missing include files, whereupon the
platform specific include directories were added to the compiler
options. Now guess what declarations fpdoc finds in e.g.
input="../rtl/unix/sysutils.pp -Fi../rtl/objpas/sysutils -Fi../rtl/inc
-Fi../rtl/win -Fi../rtl/win32 -Fi../rtl/unix -Fi../rtl/linux"

Also note that
--input="-dfpdocsystem -dHASGETHEAPSTATUS -dSUPPORT_DOUBLE
../rtl/win32/system.pp -Fi../rtl/win32 -Fi../rtl/unix -Fi../rtl/inc
-Fi../rtl/i386 -dCPU32 -dHASVARIANT -dFPC_HAS_TYPE_EXTENDED
-dHASWIDECHAR -Fi../rtl/win -Fi../rtl/win32 -Fi../rtl/unix -Fi../rtl/linux"

explicitly selects /win32/system.pp, not the (expected) /unix/system.pp

When I tried to continue the new way, by replacing more inputs by their
Windows specific versions, more problems popped up.


The addition of the win and win32 includes IMO was not a good decision,
instead the parser should use the Linux target (as you assume) instead
of the actual platform.

To reduce further discussion, I'd suggest that you provide the fpdoc
project(s) that create identical output on all platforms. Then we can
concentrate on the remaining missing links, like "Power", and delegate
the resolution of problems resulting from modified projects to the
creators/maintainers of these projects.


>> Type declarations and constants are useful even without detailed 
>> documentation.
> 
> Nonsense. ctrl-click in the IDE will get you more info by actually 
> jumping to the declaration.

Right, but what's the use of *additional* documentation at all?

It's confusing, when the documentation differs from the declarations,
and when no documentation is shown at all, because fpdoc doesn't find
the declarations in the platform specific units, this also is not a
pleasant situation :-(


>> When I started to document the LCL, I found many (Delphi) functions 
>> based on the WinAPI, so that some documentation is required anyhow.
> 
> Once more, I think you should let the WinAPI be documented by MSDN.
> No need to drag in things that are better documented somewhere else.
> But if you want to spend your time on it, who am I to stop you ?

It's even worse: when the RTL or LCL tries to implement the used WinAPI
functions in other environments, the differences have to be documented
as well. Many MSDN description details are not applicable outside
Windows :-(


> If you finish documenting actual FPC/Lazarus code, then I think your 
> mission will have succeeded.

This could be understood as "hang on the LCL documentation for the rest
of your life, and don't bother the FPC developers any more" ;-)

DoDi

P.S.: In case my preceding attachment was removed, I add it again as 
text file.
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: makeskel-windows-pp.txt
URL: <http://lists.freepascal.org/pipermail/fpc-devel/attachments/20111209/37c0e33f/attachment.txt>