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

[Bernd]

2010/7/23 Mattias Gaertner <nc-gaertnma at netcologne.de>:
> The fpdoc files for the LCL are in docs/xml/lcl.

Ok, I found them, they are there indeed, I wrongly concluded that they
are not there because it didn't find documentation for classes that it
should have found (seems to be a bug resulting from this approach) and
posted here before I looked into the folder myself. Shame on me. If I
sound impatient or even annoyed sometimes then please simply ignore
it, these conditions are usually gone after some hours and i keep
trying to understand the inner workings of Lazarus. I spent many hours
yesterday trying to understand how all the classes that are (or seem
to be but are not) involved in generating these hints are working
together and after a few hours I still did not have the slightest clue
what was really going on while my brain was just about to explode.

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.

The code looks like it is well thought out and everything seems to be
modular and extendable and and even for such seemingly tiny tasks like
generating a hint there seems to exist a whole framework of pluggable
hint-providers and whatnot with all bells and whistles but nowhere is
written how this architecture is supposed to work and what is using
what and how. Either you know it or you are completely lost.

It might all be obvious to you because you wrote it but try to put
yourself in my place, where would you even begin if you were
confronted with such an enormous amount of complicated multi-layered
but completely undocumented code? At this point I don't even care
about whether fpdoc is used to display the comments in hint windows or
if it is directly in the code if there only were *any* documentation
at all.

Another poster suggested I should start helping to improve the
documentation but it does not work this way. I am highly motivated to
help with Lazarus development, otherwise I would not spend whole
nights trying to understand other people's code, but to write or
improve documentation I need to know how it works but to learn how it
works I need at least a minimum of documentation from the original
authors or I will have to spend hours or days to find out things that
could in the end be written down in only one or two sentences. I don't
think it is ok to expect newcomers to spend weeks reverse engineering
the existing undocumented code and then write some (possibly wrong)
documentation based on what they *think* they have found out while
those who know *exactly* how it works are still alive today and could
just write down a short description of two or three sentences for
every class and method right off the top of their head that explains
*why* this piece of code is there and *who* is using it (or what kind
of code is supposed to make use of it) and *when* (under which
circumstances) is this supposed to happen.

Therefore I suggest the documentation should be written by those who
already know these things and not people like me. Doing so also avoids
the need to answer the same questions over and over again and it would
also attract new developers (or rather not immediately put them off
after looking at the obfuscated code).

> If using comments wrong they can easily obfuscate code.

Of course I suggest helpful comments. Comments that put the commented
code into the bigger picture and provide explanations about its
purpose and usage and its place in the whole architecture. I don't see
how providing an explanation for a complicated mechanism could ever
obfuscate it, unless the explanation is wrong of course.

Completely leaving away all comments will most certainly obfuscate
code of such enormous multi-layered complexity and I doubt that code
that is already highly obfuscated by the complete *lack* of urgently
needed explanations can be further obfuscated by adding these
explanations.