[fpc-devel] FPDoc and Lazarus

[Michael Van Canneyt]

On Sun, 4 Sep 2011, Hans-Peter Diettrich wrote:

> Michael Van Canneyt schrieb:
>
>>> <td><p>  </p></td>
>
>> Where do you see 'empty' paragraphs ?
>
> See above. Even if the &nbsp may be inteded to form a gap between the
> columns, I don't unterstand why these (and the other columns) are
> embedded in an paragraph.

In my book, empty means <p></p>.

As for why: I don't know.

>
>
>>> These messages are quite vague, since this topic contains several tables, 
>>> and I also could not find out the reason for above messages. The output 
>>> looks as expected, and there exists no "#text" in the topic source. Are 
>>> topics treated differently from other element descriptions, making <link>, 
>>> <b> or <var> invalid?
>> 
>> No. It means your text structure is invalid. Typical errors are
>> 
>> <descr>
>> some text
>> <p>
>> </p>
>> </descr>
>> 
>> this needs to be
>> 
>> <descr>
>> <p>some text</p>
>> <p>
>> </p>
>> </descr>
>
> Argh, such constructs are really hard to find :-(

Not really, the error message tells you where to look.

>
> Can <printshort> tags import such unparagraphed text?

Yes.

>
>
>>> Can somebody suggest an XML validator, that would give more precise 
>>> information about the location of invalid tags?
>> 
>> That won't help you, since there is no fpdoc DTD (any more). There used to 
>> be one. I will see if I can find it.
>
> Yes, please.
>
>
>>> One more: --project seems not to work, fpdoc complains about invalid 
>>> option and missing package specification?
>> 
>> Probably your fpdoc is too old. You should use the one from SVN.
>
> You are right, I used version 2.5.1.
>
> Now I tried again, using version 2.7.1, and the unmodified sample-project.xml 
> crashes with exception: Unable to open file "dglobals.xml" :-(

The sample project is meant as a sample for studying, not for actual work.

>
> It's not really nice when fpdoc crashes with unhandled exceptions,
> instead of skipping missing or invalid files.

Skipping missing or invalid files is the worst you can do.
a) the output will be invalid anyway
b) you have no warning that something is wrong.
Consequently, fpdoc stops on error.

I assume you would not want the compiler to happily ignore errors in your code 
and then go on to produce an invalid program ? 
It's exactly the same principle for fpdoc.

Michael.