[Lazarus] FPDoc tracker

[Hans-Peter Diettrich]

Martin schrieb:

>> One solution were another directory, holding all "old" versions of the 
>> primary files, so that these files can be compared to the current 
>> versions. The comparison can be improved by checksums or similar 
>> means, so that a direct file-by-file comparison can be avoided. 
>> Perhaps also a "diff" tool can be used to find and report all 
>> differences between the files in these directories?
> 
> The 2ndary file could have a checksum of the node n the primary file. 
> then it can check, if the primary file was modified. The checksum must 
> be in a way, that ignores formatting, etc. (maybe even minor spelling 
> fixes)

After some research I think that diff is the simplest starting point. It 
allows to compare directories, so that all changes can be kept in one[1] 
output file (ToDo list).

Then the tracker can use that file to navigate in the XML files, to find 
the affected elements, and finally the processed differences can be 
removed from the list (for later editing). After all diff sections[2] of 
one file are removed, the new file is copied to the reference/backup 
directory, for subsequent compares.

The actual work typically has to be done on different XML files, in the 
secondary directory. This part deserves further work...

But there's another use case, when code has been moved across units, 
like the recent move of the TCustomNotebook class(es) from ExtCtrls into 
ComCtrls. While this could be automated as well, I think that its easier 
to cut&paste the affected parts immediately in the XML files. Later on 
the code positions and hashcodes can be stored in the XML files, by 
makeskel, with appropriate handling of inserted/deleted/moved elements.

More automatisms can be added to makeskel, like inserting links to 
inherited documentation - is this required? IMO it would be a good idea 
to store a reference to the ancestor class with *all* classes, 
regardless of whether a derived class has its own documentation.


[1] How to find the directories containing separate package 
documentation, outside of $lazarus/docs/xml? Where is the list of all 
known packages stored?

[2] What's the exact meaning of the line numbers in the diff sections? 
Do they strictly correspond to the original line numbers, or line 
numbers after preceding changes (sections) have been applied?

DoDi