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

[Mattias Gaertner]

On Thu, 22 Jul 2010 16:38:03 +0200
Bernd <prof7bit at googlemail.com> wrote:

>[...]
> It will show the text of the above comment when hovering the mouse
> over any occurrence of this method call. This is a GREAT feature.

:)

It also shows the text of the fpdoc nodes.

 
> Now here comes my complaint: 99% of all code in LCL and Lazarus seems
> to be completely undocumented, in some places there are thousands of
> consecutive lines without any single comment, types and variables and
> method after method with funny names, obscure parameters and obscure
> return values are declared without any mentioning of what they might
> be good for, *who* or what kind of code at the other end of the
> project might use them and *when* and *how* and under what
> circumstances.

Documentation about how to use a LCL function/property should be put in
the fpdoc nodes. Hints about implementation can be put in comments.

 
> Suggestion: Make this hint window even more useful by letting it also
> pop up for the currently highlighted item in the *autocomplete* list
> (other IDEs like Netbeans or Eclipse are doing the same) and then
> people might start seeing the ***usefulness*** of putting a small
> descriptive sentence above every method about what it does or how it
> is used and also sometimes even a whole paragraph of documentation for
> not so obvious things.

Such a window already exists, but for various reasons I have not yet
enabled it. See below.

 
> Make everything you could possibly do to further increase the reward
> for the "burden" of documenting source code.
> 
> Documenting code is really not as hard as it seems, I do the same
> thing with all of my code in all languages I use. Whenever something
> finally works and I can lean back and proudly look at the functions,
> classes or methods that had cost me some nerves to implement I start
> writing some lines of explanatory text about this adventure, trying to
> formulate what is going on like i would explain it to somebody else.
> Sometimes more than 50% of my code is only documentation. sometimes
> only 3 words per method, sometimes 10 lines explaining why the method
> is needed and why it is implemented exactly the way it is and maybe
> some words about its side effects.

I'm somewhat jealous. I seldom have this moment of 'lean back'.

 
> I don't use any of the fancy javadoc parameter declaration stuff that
> is available in some languages, redundantly declaring things that are
> already obvious from the function signature a second time would indeed
> be a burden, i just write a text comment for every class and method
> containing things that are not obvious.

Obviously the term 'obvious' differ much.

 
> If Lazarus can display such comments in all places where this might be
> appropriate (it does already in some places but in the autocomplete
> list it would be obviously useful but is still missing¹)  I am sure
> that people would start commenting their code.
>
> _________
> ¹ If nobody wants to implement it then I will try to make a patch for
> it myself (and comment it!), once I have successfully found my way
> through the undocumented synedit code (or wherever this might be
> located, it is not easy to find, its all completely undocumented)

The hint for the completion box has almost nothing do with synedit,
but a lot with the codetools, how the IDE uses the codetools, the code
help system, the code help viewer and the LCL features on the various
platforms of showing windows at the correct position and the right
activate/focus messages.
The completion box is a central feature of the IDE and must stay fast
and snappy. The hint is secondary. Gathering the hint information takes
some time. Making it fast enough is not trivial.
The other point is the code viewer. It needs scrollbars and
interaction, so it can not use a simple hint window. This is creates
some focus and window ordering problems.
There is progress in all these areas, so the completion box hints will
come. But I can't say when.


Mattias