FPDoc issues many warnings about unknown link targets. Some of these seem to result from intrinsic types, e.g. for PSmallInt the target SmallInt does not exist. It doesn't look good when the docs do not include the most basic types, like Boolean, Byte, Char, Pointer etc. :-(

The same problem with Integer referring to SmallInt (missing, of course), what looks quite inappropriate nowadays. IMO a 16 bit Integer doesn't make sense in win32(!)\system.pp (including systemh.inc, see line 92), and on other platforms as well.

When the basic types cannot be documented due to missing explicit declarations, at least a topic covering all basic types should be added, with all references to these types (e.g. from Integer) redirected to that topic.

Or these entries should be rewritten from <element> into <topic>, so that all links can find their targets? I just tested this solution, and it works, except that the topics are not listed as types in the index. But then also the <short> descriptions should be renamed into <descr>, because the short description of an topic becomes its title! E.g.:

<topic name="ShortInt">
<short>ShortInt</short>
<descr>A signed 8-bits integer</descr>
</topic>

What about Char? Currently it's described nowhere, and with the introduction of Unicode the basic type should become AnsiChar, with the generic Char=AnsiChar or WideChar, depending on the actual/future declarations.

BTW: "Power" also deserves an update, it seems not to be declared in system.pp?

DoDi

Hans-Peter Diettrich wrote

exist. It doesn't look good when the docs do not include the most basic types, like Boolean, Byte, Char, Pointer etc. :-(

Those are all basic built-in types. Built into the compiler, not defined in the RTL (as far as I know), but rather the System unit, thus the problem. But it is false to say they are not documented, in fact they are well documented in the FPC Language Reference document. But this is not directly reference-able (if there is such a word) from the RTL fpdoc output.

This is where DocView comes in very handy again. DocView simply concatenates, at runtime, the Language Reference, RTL and FCL inf files. So then I see them all in the DocView table of content or Index, and they are all searchable. This is very handy for a developer (especially while offline), and why I always hammer the fact that you need a descent documentation viewer and help file format. Excellent documentation means nothing if you can search and find something.

Graeme Geldenhuys hat am 2. Dezember 2011 um 08:05 geschrieben:

[...] Excellent documentation means nothing if you can search and find something. 

You make every developer of search tools/engines proud.   
There is some Confucius' wisdom in your statement. The opposite with "can't" is true too, but is IMO banal. 
 
 
Mattias
 

Hans-Peter Diettrich wrote

FPDoc issues many warnings about unknown link targets. Some of these seem to result from intrinsic types, e.g. for PSmallInt the target SmallInt does not exist. It doesn't look good when the docs do not include the most basic types, like Boolean, Byte, Char, Pointer etc. :-(

They are language (and thus compiler) built-ins and are therefor documented in the language reference.

That said, I'm willing to include a small topic in the system unit which explains this, and lists the types involved.

The same problem with Integer referring to SmallInt (missing, of course), what looks quite inappropriate nowadays. IMO a 16 bit Integer doesn't make sense in win32(!)\system.pp (including systemh.inc, see line 92), and on other platforms as well.

In FPC mode (the default mode), Integer = Smallint. This is therefor correct.

The objpas unit (included implicitly when you use mode delphi or objfpc) contains the Integer = Longint definition.

When the basic types cannot be documented due to missing explicit declarations, at least a topic covering all basic types should be added, with all references to these types (e.g. from Integer) redirected to that topic.

The reference is not possible, since they are in the languague guide and references to that are impossible.
(I also happen to think that these references are totally superfluous, but that's more a matter of opinion)

Michael.

You will be pleased to hear then, that we've developed - in FPC - a search engine for the HTML docs :-)

Michael.

Michael Van Canneyt wrote

You will be pleased to hear then, that we've developed - in FPC - a search engine for the HTML docs :-)

Excellent. How fast does it do searching across the RTL and FCL HTML docs? Does it need to first build a search/keyword database?

I remember using Tipue (www.tipue.com/) years ago with fpdoc generated HTML. But the search / keyword database was *huge*, causing relatively slow searching, and a real pain to generate that search database or keep it up to date.

Graeme Geldenhuys wrote

Excellent documentation means nothing if you can search and find something.

Typo alert!
The above should read: "Excellent documentation means nothing if you _can't_ search it and find something."

It does. This is a one-time operation.

I remember using Tipue (www.tipue.com/) years ago with fpdoc generated HTML. But the search / keyword database was *huge*, causing relatively slow searching, and a real pain to generate that search database or keep it up to date.

The time depends on the back-end, but all back-ends returned results in less than 0.7 sec. Considering the size of the databases involved, this is OK.

Currently there are 3 backends: custom made, sqlite and Interbase. No surprise, the custom made one is fastest.

Michael.