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

[Bernd Kreuss]

Ok, I promise I will try to not further mention my dislike for the fpdoc
-for-everything approach anymore. If some documentation about the inner
workings of the IDE will finally be written some day and it must all be
in fpdoc then let it be in fpdoc, I can live with it better than with no
documentation at all.

The usage of all the units and APIs for developing my own applications
does not seem to be a big problem (at least not for me), somehow I am
always able to find the information I need relatively easy. When
developing my own application from scratch I only have to deal with the
public LCL (and other) interfaces and their documentation that is at
least partially there and that have been used by many other people
before me and that are quite easy to understand and the complexity as
seen from the outside is very low.

Martin wrote:
> As I said, for now, rather than discussing, what everyone knows => ask 
> questions what you actually want to know. That is much more productive 
> for everyone

Ok, then here the concrete things I am currently researching. As I
already mentioned I am interested in the hints. Some things seemed not
so consistent to me and so I just wanted to dive right into the code and
see if there is an easy way to make the hints in the code browser and
the (not yet existing) hints in the code explorer work like the hints in
the source editor. I quickly found out that the hints in the code
browser are working completely different from the hints in the source
editor. They don't even look up the fpdoc or look up anything, they
simply show the code and the source position.

Now have the whole IDE loaded in the debugger and looking at the
callstack while the IDE is trying to generate a hint for the source editor:

> #0 TCODEHELPMANAGER__GETHTMLHINT(0xb5cacd60, 51, 7365, [CHHOCOMPLETE..CHHOCOMMENTS], 0x0, 0x0, true (54), 0xb76dcaa0) at codehelp.pas:2200
> #1 TIDEHELPMANAGER__GETHINTFORSOURCEPOSITION(0xb5e3e278 '/home/bernd/lazsvn/lazarus/trunk/ide/sourceeditor.pp', {X = 51, Y = 7365}, 0x0, 0x0, 0xb7581500) at helpmanager.pas:1320
> #2 TMAINIDE__ONSRCNOTEBOOKSHOWHINTFORSOURCE(0xb5b8c220, {X = 417, Y = 387}, {X = 51, Y = 7365}, 0xb7b610e0) at main.pp:15072
> #3 TSOURCENOTEBOOK__SHOWSYNEDITHINT({X = 756, Y = 556}, 0xb5b118c0) at sourceeditor.pp:7378
> #4 TSOURCENOTEBOOK__HINTTIMER(0xb7595120, 0xb5b118c0) at sourceeditor.pp:7315
> #5 CUSTOMTIMER_TCUSTOMTIMER_$__DOONTIMER at :0
> #6 CUSTOMTIMER_TCUSTOMTIMER_$__TIMER at :0
> #7 GTK2PROC_GTKTIMERCB$POINTER$$LONGBOOL at :0
> #8 ?? at :0
> #9 g_main_context_dispatch at :0
> #10 ?? at :0
> #11 g_main_context_iteration at :0
> #12 gtk_main_iteration_do at :0
> #13 GTK2INT_TGTK2WIDGETSET_$__APPWAITMESSAGE at :0
> #14 FORMS_TAPPLICATION_$__IDLE$BOOLEAN at :0
> #15 FORMS_TAPPLICATION_$__HANDLEMESSAGE at :0
> #16 FORMS_TAPPLICATION_$__RUNLOOP at :0
> #17 INTERFACEBASE_TWIDGETSET_$__APPRUN$TAPPLICATIONMAINLOOP at :0
> #18 FORMS_TAPPLICATION_$__RUN at :0
> #19 main at lazarus.pp:113

(I found no other way to find out what exactly is going on with this
hint window thing than using a breakpoint and singlestepping it in the
debugger because at some point it would call a procedure variable where
I had no clue to where it would point at runtime because the code is so
incredibly far spread across so many units and goes through so many
abstraction layers that I have no idea how to find this out from looking
at this gigantic codemonster alone.)

TCodeHelpManager.GetHTMLHint(
  Code: TCodeBuffer;
  X, Y: integer;
  Options: TCodeHelpHintOptions;
  out BaseURL, HTMLHint: string;
  out CacheWasUsed: boolean): TCodeHelpParseResult;

seems to do the interesting things It will look up fpdoc and comments
and do everything to create a useful hint.

I assume this is the "correct" way of creating the contents of a hint
window. I was initially hoping there would just be some hint window
class that i can just instantiate anywhere and just have to give it the
source code position (or whatever type of data is usually used to denote
a piece of code) but it seems to work differently. It seems to first
create the hint contents and then later use them for a hint window to
fill it.

Would I have any chance to try and use the above method to create the
hint string in the code browser window? I remember having seen there a
node variable that has a TCodeBuffer somewhere in it and also X and Y
seem to be accessible. Would this be possible? From where do I get a
TCodeHelpManager object? Is there already one around somewhere that I
can simply access or do I have to instantiate my own?

Or is this all complete nonsense and i should not mess around with it at
all because it will all be completely replaced and rewritten?