[Lazarus] "show declaration hints" has more power in it than is really used

[Martin]

On 23/07/2010 13:34, Bernd wrote:
> Its not only the fpdoc thing or how to generate documentation, this is
> only of secondary interest to me now.
>
> At the moment I am just trying to understand the code of the source
> editor, the autocompletion and the hints but I cannot find anything
> that will help me see the big picture. This is why I am permanently
> concerned with comments, I am interested in how comments could be used
> by the IDE, I am interested in how these things are implemented at the
> moment (I want to help improving it once I have managed to understand
> it) and of course I am interested in the comments themselves (or the
> complete lack thereof) for achieving this goal of understanding the
> code.
>    

Well a broad overview:

- Components/Synedit:
   concerned with editing text; very little IDE related code

- Components/Synedit/SynCompletion.pas
   The class for the completion dropdown. (There are 2 completion 
modules in there)
   - They are plugins to synedit (one plugin, can be plugged to many edits)
   - They have callbacks to get the data
   - There is a decendend of TForm => which is the actual dropdown, it 
contains the code for hint placement, and callbacks to get the hint content:
        procedure TSynBaseCompletionForm.ShowItemHint(AIndex: Integer);

- ide/SourceEditor.pp
   Wrapper for SynEdit, glues it into the IDE
   - Contains:
     TSourceEditCompletion=class(TSynCompletion)
     which extends the dropdown, for pascal completion

- ide/SourceEditProcs:
   code to handle the display of each item in the drop down 
(color/format/etc)

- components/codetools/*
   Actually provides the content. Parses the source, looks for comments, 
reads the fpdoc, .....

  details

2) Someone wants to extend Edit, needs to know what else it triggers in 
the Edit or from where it is triggered.
  - internals: How it interacts with the rest of edit, where it is used 
in edit
  - implementation: How is the data calculated, for example how are 
folded lines found and mapped, are they stored in a simple list or a tree?


On a first glance, if the source is to complicated to explain tiself, 
the you need comments.
But actually, then you need to clean up your source, so it becames 
readable again.

Of course readable, is defined on the readers ability, and that varies 
=> but then for the more experienced reader any comment explaining the 
obvious "to him" just is in the way of the big picture.

So comment will always be a conflict of interest => unless they can be 
hidden => but that forces everyone to use an editor with the 
hide-function, rather than their personal choice....