[fpc-devel] Errors with make rtl.chk on Windows

[Graeme Geldenhuys]

On 3 December 2011 16:03,   wrote:
> First, it keeps the actual documentation XML more "clean" in the sense that
> it contains only documentation, and not 'organizational instructions'.

The documentation is useless unless you have the associated *.pas
unit. As you even mentioned earlier. fpdoc doesn't include
documentation if it can't find the associated identifiers, units etc.

So no matter how you think about it, the XML documentation is closely
tied to the source code it documents. After all, it is API
documentation we are talking about.

> I think it would also require the documentation writer to foresee
> organizational issues and parametrize them in the XML, which I think is
> something the documentation writer should not have to care about.

API documentation writers are technical people, probably a programmer.
They *will* have to look at the source code, no know how to document
each API.

I think you are confusing the type of documentation. FPC Language
Reference for example is a totally different type of documentation to
API documentation. The latter needs a programmer or at least somebody
looking at the source code to know what it does, before they can write
documentation or code examples.


> Speed is also an option. If we start allowing macros, then as an end result
> the macros must be processed in the whole XML file. The documentation XML is
> rather big; the project file is small.

To produce API documentation with fpdoc, you have to read all the XML
files anyway. The macros I'm talking about will only be used in the
<unit> take, nowhere else in the documentation. The macro will should
normally point to the root of the source code directory - wherever
that is on each persons computer. The structure of the source code
from that point on (deeper than the root of the source directory) can
be assumed to be constant (or change very very little). Even now, if
the source code directory  changes, the documentation scripts will not
work. All the --input parameters will have to be adjusted. So the
inclusion of that information in the XML file adds no extra overhead.

I'm just thinking in terms of minimizing the amount of files we need
to carry around if we want to generate documentation.

The other benefit of having the unit information inside the XML file
means you can extend whatever documentation tool you use, so it can
for example generate documentation just for that one unit, or one XML
file. As Hans-Peter mentioned, a preview to see if you documentation
for a specific unit  or class etc looks correct.

> In true unix philosophy, I think it is better to have many small and simple
> tools cooperating well

Yes, I agree with this philosophy, but no matter how you look at it,
API documentation is closely tied to the code it is documenting. So
keeping the information together in one place seems logical too.



-- 
Regards,
  - Graeme -


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