[Lazarus] Documentation and Help for Lazarus (content)

[Hans-Peter Diettrich]

Mattias Gärtner schrieb:

>> In PasDoc2 I imported inherited descriptions automatically, so that 
>> only really overridden behaviour must be documented, when it really 
>> does something different, or when it implements an abstract and 
>> unspecific method. This can also reveal in which class a method or 
>> property has been introduced, when the search starts in TDerived.ident 
>> and the help mentions TBase.ident.
> 
> The fpdoc help of the IDE (mouse hints) shows every fpdoc entry 
> including all ancestor entries and all pasdoc comments, including all 
> ancestor entries.
> We have already a bug report from Graeme that this is too much.

It's too much, indeed. It IMO also shows that inline documentation (in 
the source code) is not very useful in class trees, where every derived 
class would either have no immediately visible comments, or would 
duplicate (possibly outdated) specs from the base classes - a 
maintenance nightmare :-(

For separate documentation a flag may be helpful, indicating whether the 
entry should replace or only extend the information, found in ancestor 
classes. A flag also could indicate the availability of information in 
ancestor classes, so that it's immediately obvious where missing 
information has to be added at all (newly introduced item), and where 
duplicate information should be omitted (inherited item).

DoDi