2010/7/23 Mattias Gaertner <nc-gaert...@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. -- _______________________________________________ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus