[Lazarus] FPDoc editor and document placement

[Hans-Peter Diettrich]

Mattias Gaertner schrieb:

>> I'm really confused now :-(
> 
> I too, when I hear the reasoning of such programmers, but this universe
> is not that simple.

Good solutions tend to be simple ;-)

>> First FPDoc Editor requires that the source file is part of a package. 
>> Then you say that this is not (no more?) a requirement. So what's the 
>> use of added pathes?
> 
> When you create a new fpdoc file, the fpdoc editor requires a package.
> When searching a fpdoc file of a unit the IDE searches in the above
> path too. I know no one that uses this. You are the first wanting to
> document units without a package.

Everything happens once for the first time. That's what makes coders 
earn a continued living ;-)


>> When a help directory can be specified whenever a non-packaged file is 
>> documented, the help system (later) has no idea in which directory that 
>> help file has been created, and consequently must search the entire help 
>> path.
> 
> Yes. In most cases the search path has only one directory. In fact I
> don't know a case with more than one fpdoc directory.

I just have increased the FPDoc path box (to alClient), because it 
contains a whole bunch of pathes (for the lcl, rtl...).


>> Until here a single NonPackaged directory would be sufficient to 
>> hold all such help files. When multiple such directories are allowed, 
>> the help system still cannot know whether Unit1.xml should be loaded 
>> from directory X or Y :-(
> 
> Is this a theoretical case or do you have any real life example where
> this is a problem?

Fortunately I don't have an example right now, but shit happens...


>>> The current model is this: I download a
>>> package from the net, open it in the IDE and can press F1 on an
>>> identifier to get help. All details are up to the package maintainer.
>> Details are not (only) up to the package maintainer, but also are up to 
>> the package installer and help system.
> 
> An option to override and use some different fpdoc files would be nice.
> But this is for expert users. I think the help must be done for
> newbies, experts come here second.

Newbies will use F1, while power users will use the FPDoc editor.


>> As mentioned already in my preface, the FPDoc Editor is of my actual 
>> interest. As I could figure out till now, everything boils down to the 
>> (fragile) determination of the owner of an source file, based on only(?) 
>> the module name. When that module name is unique,
> 
> It is not always unique.

What will happen in this case?

>> knowledge of the owner 
>> is not required, it only can speed up the first search for the according 
>> help file. My impression is that all(?) registered packages are scanned 
>> at IDE startup, so that instead the registered help directories could be 
>> scanned as well.
> 
> Only the lpk files are loaded.

I get any number of GetFPDocFilenameForSource calls on IDE startup. 
Since the SrcToDocMap cache is empty at that time, SearchInPath is 
called until a help file can be found on disk. This way the candidate 
directories are scanned very often (once for every source file!), where 
a single scan of every directory, for all contained files, would be 
sufficient to fill the cache at once.

DoDi