[Lazarus] Lazarus documentation

[Hans-Peter Diettrich]

Mattias Gaertner schrieb:

>> Eventually all documentation (about packages, tools etc.) can be stored 
>> in independent SVN projects, which are added to /docs/xml/ as subprojects.
> 
> ?

This would allow to gather all available documentation (locally) in one
directory tree. The formatted output will go into the same tree, when
the user builds the final documentation. The build tool and help viewers
will have to look only into one location, in order to find all
documentation to create or show.


>> 3) Packages
>> We should have at least documentation skeletons for all packages, so 
>> that everybody can see what's missing. I'm willing to create the 
>> skeletons, when their integration into LazDE is established (see below).
>>
>> Can somebody try to create a documentation skeleton for any package, 
>> based on e.g. an .lpk file, that can be opened for further edits in 
>> LazDE? I found no way to do so yet :-(
> 
> What do you mean?

You didn't try to do what I suggested, didn't you?

>> 4) LazDE
>> LazDE has a nice GUI for adding bulk documentation, or for filling the 
>> gaps left by the FPDoc editor. Unfortunately I achieved, somehow, that 
>> LazDE cannot open any package documentation any more, and also not the 
>> new documentation created with FPDoc Updater. At least should it be 
>> possible to add existing XML files to a package, as long as LazDE cannot 
>> create documentation for packages and all contained files itself.
> 
> Please create a bug report.

Two bugs already have been fixed :-)

The remaining problem is that LazDE cannot open the docs for a package
in an single tab. Every tab contains an degenerated tree, containing
only three nodes: packages - <package> - <module>, and every module must
be opened manually.

IMO an entry type "moduleref" is missing, which could be used in package
doc files to refer to the contained modules. Alternatively a <module
file="..."> entry, instead of <module name="...">. These entries then
could be used to populate the package node in the treeview. IMO Makeskel
doesn't save the used units in otherwise empty (package) unit files, so
that opening e.g. lcl.xml will not result in a list of modules for the
lcl package. Other xml files seem to contain references to the used
units, with e.g. <element name="Classes">, which could be changed into
<uses name="...">.

Alternatively LazDE could check the package name when loading an module
file, and add the module to an already existing package node of this
name. Or when loading an empty skeleton file, only containing an package
name, it could search for all module files with this package name, and
open them automatically. I've started to add according code, but I do
not yet understand the object managment (doc file ownership) in LazDE,
that would allow to handle multiple doc files in an single tree.


Finally I'm missing a feature to review documentation and source code in 
sync, as I implemented in PasDoc2 (branch of the SF pasdoc project). I 
understand that this is not easily feasable, since the FPDoc structure 
does not contain references to the declarations in the unit files. Such 
a feature may be better located in the FPDoc editor, which could be 
extended with navigation buttons to the preceding/next (undocumented) 
element in a module.


> I guess Michael welcomes patches for LazDE.

I saw that he also read my suggestions :-)

DoDi