[lazarus] Interface documentation

[Mattias Gaertner]

On Wed, 13 Aug 2003 11:16:32 +0200
Micha Nelissen <M.Nelissen at student.tue.nl> wrote:

> Hi,
> 
> Currently in the win32 interface, every function in win32winapi.inc is 
> documented. Is the text for each of the functions in the GTK the same? 

Probably not. There are notes about the gtk implementation.


> Shouldn't the documentation be in the interface base class? If we add 
> another interface it should adhere to TInterfaceObject.function 
> specification.
> 
> I am saying this because:
> 1) the documentation on the functions would be more centralized in 
> tinterfaceobject.
> 2) for gtk CreateCaret does something different from the win32, so 
> actually we should define what CreateCaret should actually do (for 
> example use the GTK semantics) and then make the win32 interface adhere 
> to it.

I think the same.
The lazarus documentation should include the general specifications plus all
additions and differences. It would be nice to see the general specification
in the source (interfacebase) as well, but I think, it means a lot of extra
work to maintain the redundancy. 
The current plan is to use fpdoc and its editor fpde. Both need some work,
but I think, we can start with them.

ToDos for the docs:

1. enhance fpdoc:
- creating html files on the fly (s.g. has already started this)
- updating the xml files, when sources have changed
- better localization
- smaller html files

2. enhance fpde:
fpde shows at the moment only the xml entries. It would be very helpful, if
fpde would work together with the IDE, so that one can edit the source and
the doc at the same time and without manual search and jump. Two
possibilities:
2.1 Write a command line interface like gdb, or an RPC interface or an
tcp/ip protocol
2.2 Since fpde uses fpgtk, it should not be hard to convert fpde to a LCL
program and add some functions, so that it can be used as an IDE plugin.

3. Write a small fpdoc server, that converts requests of the form
"buttons.pp: TBitBtn.Glyph" into html pages.

4. The browser
We can either add a small webserver to the IDE and the user decides which
browser to use, or we provide a browser of our own. The IDE must be able to
remote control the browser. I don't know, if there is an easy way to remote
control any kind of browser.


Mattias