There is something that could boost productivity and learning curve of new developers by a factor of three at least and all needed infrastructure (at least the hardest parts) for this feature seem to be implemented and working already, it is just not (yet) used to its full potential.

I have one suggestion and one complaint, they closely belong together and implementing the suggestion will help improving the situation I am complaining about by introducing a great *reward* for the needed (and currently lacking) discipline of documenting the source code. Yes, let me repeat this enormous frivolity: "documenting the source code!"

If the option "show declaration hints" in options->editor->automatic feaures is activated (seems to be default) then it will show a little hint window whenever the mouse hovers over an identifier and it will display some information that it can parse out of the source about its declaration.

The most important GREAT feature of this little popup window is that it will show the (* COMMENT *) that immediately precedes the declaration.

(* return the foo of the something for the given bar.
Will be called by foobar on every foobaz event. The
x component will be cached after the first call so it
does not cost anything to call this on every foobaz*)
function TSomething.GetFoo(bar: TBar): TFoo;
begin
    // [...]
end;

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.

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.

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.

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 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.

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)

[...] 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.

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

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

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

Obviously the term 'obvious' differ much.

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

Bernd 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 fpdoc entries. That is even more useful ;-)

Many classes and methods are already documented in fpdoc. Those are

external

files which are used to generate the separate help packages but are also

parsed and shown by the Lazarus IDE already. You just have to specifiy the

path(s) to those docs (Settings --> FPDoc-Editor --> Paths).

In other words: the feature is there, and already in use. What is indeed

missing, is still a lot of documentation. Feel free to add them using the

fpdoc editor of Lazarus :D

2010/7/22 Andreas Schneider :

Many classes and methods are already documented in fpdoc.

Ok, now I'm looking for these files but it seems It is not so easy to find them anywhere on the ftp server or the website or sf.net. I am using one of the recent snapshots and It would be nice to have a snapshot of these fpdoc files that belong to the downloaded lazarus version that i could just unzip into the folder where it belongs or even better: a .deb or .rpm or a windows installer.

If these files are what is needed to make Lazarus more complete and usable and context sensitive help available they should not be hidden from the user. IMHO they should even be part of the standard lazarus installer and if these fpdoc files are somehow an integral part of the source that is needed for working with it and if the installer installs the sources it should also install this "other half" of the source.

(I will continue searching for these files and hopefully find them somewhere after I have completed this email)

Those are external files

I can not applaud this decision but unfortunately I won't be able to convince the developers that this is fundamentally wrong. It seems like too much effort has already gone into this to throw it away now, altough this would be the wisest decision. IMHO code should be documented in the code itself. This is what I (and many others) have found most useful, most portable and most easy to handle. The process of documenting code (something most programmers seem to find extremely difficult and hard to do and therefore often don't do it at all) should not be further *complicated* by forcing the usage of separate files that must be kept in sync with the code and the usage of a specialized tool. I hope the fpdoc thing can generate itself from source comments alone that are already present in the code.

BTW: The statement somewhere in the fpdoc manual that code becomes "obfuscated" by properly commenting it is ridiculous!

The fpdoc files for the LCL are in docs/xml/lcl.
Most packages put their fpdoc files into a sub directory 'docs'.

The IDE hints read the fpdoc files directly. No need to install anything.
But the fpdoc files also contain descriptions, examples, images, links and topics. This information is not yet shown in the hints. You can see the html output of fpdoc when pressing F1 on an identifier. You can install lhelp for an offline help viewer.

Lazarus supports comments, fpdoc and other formats. If you prefer comments, use comments.
If using comments wrong they can easily obfuscate code. And comments are limited. The LCL needs examples, links, graphics, topics and eventually translations.

Mattias

IMHO, Lazarus should hold a list of all public declarations done in the RTL and the LCL and when pressing F1 with the cursor on some name, it should show the appropriate help, even if is not found in any unit mentioned in the uses clause - such as it works today. (providing a selection list when multiple alternatives are found).

-Michael

+1

Zitat von Michael Schnell :

It is already on the todo list.
See for example the 6th point here:
http://wiki.lazarus.freepascal.org/Lazarus_for_education#ToDos

Mattias

2010/7/23 Mattias Gaertner :

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.

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....

Maybe this very global text could be enhanced by a more concrete suggestion like the one above or perhaps some other that might be more appropriate.

-Michael

Note:
There is already a tool to see all public declaration: View CodeBrowser. It does not only list all public declarations of RTL and LCL, but all FPC packages, your project and all used packages. Depending on your platform there are about 200 thousand identifiers and collecting them takes a few seconds to several minutes (speed mainly depends on your disk speed).
It is invoked for example when you right click on a compile message 'identifier xyz not found'.

F1 should not only show declarations but also topics. F1 should "simply" ask the installed help databases for the not found identifier, maybe as keyword search. A simple fpdoc database can not answer this yet, but lhelp could and Graeme has written yet another help database.

There are many possibilities. That's why I put a broad todo.

Mattias

While this is an absolutely great feature, I feel that it's not intuitive (especially for new users) that you need to compiler the source code before getting help on a function he wants to use but does nit know where to locate..

just providing the same functions as you get when right-clicking -> "find identifier" in case F1 does not find a specific help (as the appropriate unit is not included) would be a good start....

-Michael

2010/7/23 Martin :

It depends what the reader knows about the internal architecture of the program and what is obvious to him but to nobody else.

but then for the more experienced reader any comment explaining the obvious "to him" just is in the way of the big picture.

No. This is simply not true. Comments in the code are not for yourself, because then you would not have to write any comments since *you* already know how it works. Comments are for *other* people who might later read your code and don't yet know how it works. I cannot believe that we are seriously discussing the helpfulness or necessity of comments and that there could be any doubt about it. Of course comments are *always* helpful! There simply is no reason to leave them away, unless you intentionally want nobody else to ever read or understand the code.

How can a comment ever be in the way? If it tells you nothing new you simply ignore it. We are talking about small comment blocks at the method headers. How can 2 or 3 light green lines *above* a procedure definition or above the class definition come into your way while you are working *inside* the procedure body?

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....

fpdoc forces everybody who wants to read the code to use Lazarus because otherwise half of the code is missing ("half of the code" meaning the comments that IMHO are substantial part of any readable code).

You misunderstood me. Still I stand by my words: "it depends on the experience of the reader.

Example:

I may declare a class:

TAVLTreeNode = class
   FLeft, FRight, FParent: TAvlNode;
   FBalance: Integer;
end;

- Now if the reader knows what an AVL tree is, there is no comment needed, it is perfectly self-explaining.
- If the reader doesn't know, but does know what a tree is, then I only need a comment for FBalance.
- And if the reader doesn't even know what a tree is, then I need a hell lot of coments...

So what amount of comments is right? and how many lines should it have? If I put a 20 line explanation in ther about AVL trees => then any experienced reader will be annoyed.

So do I expect the reader to know "well known" data structures, design pattern, and similar? and where does "well known" start? That term has a different meaning for everyone.

again an example
(the example is incomplete, it doesn't handle the case of an empty array => anyway: it's an example)

   m := SomeArray[0];
   for i := 1 to length(SomeArrar) do
     if SomeArray[i] < m then
       m := SomeArray[i];

Quite readable, and I know at a glance what it does, I need no comment there.

In fact I doubt that the following is more readable, or if part of a longer stretch of code, if it would increase the readability of the overall code (spreading it out, makin less of it fit on your screen

   // Start with the first value of the array.
   // This value will then be compared to all other values in the array
to see if any of them is smaller
   m := SomeArray[0];
   // start comparisation with 2nd value (index=1) of array,
   // since we already read the first value
   for i := 1 to length(SomeArrar) do
     // check if it is smaller than the smallest value found
     if SomeArray[i] < m then
        // if it is, replace the smallest value found by the new
smallest Value
       m := SomeArray[i];
    // Now m is the smallest value that was found in the array

Don't say those comment are silly.

I said it depends on the level of the reader. I fthe reader of the code is a total beginner, who hasn't done more than "hello world" then he will need all of those comments. But certainly to anyone (but the beginner) readability went down.

Now yes this example may be a bit far fetched. But at any level of code complexity (assuming it is written in a clean style), there are people who look at it and understand it at a glance, and people who need more or less comments.

So the same comment will be useful to some, and useless (if not counter productive) to others (and by others I don't mean the original author of the code)

- What if I don't have syntax highlighting?
- what if I compare the code o this procedure, to the code of the one right before => then the comment means I have to scroll more
- what if I search for some identifier, and my search results contain many lines in comments, where the word is used as English word and not at all related to the identifier I was looking for?

fpdoc can be compiled into chm and other help formats => allowing you to open the help in a window next to your code editor.

But yes, whatever method you choose, those who do not like it have to suffer.
Some people suffer if it is comments, other suffer if it is fpdoc

One point we can probably agree on:
Everybody suffers, if there is no doc at all

Bernd wrote

Comments are for *other* people who might later read your code and don't yet know how it works.

+1

plus they are also very helpful to you when you come back some time later and don't remember what's going on or why ;)

comments are *always* helpful! There simply is no reason to leave them away, unless you intentionally want nobody else to ever read or understand the code.

that's known as "job security" ;)

2010/7/23 Mattias Gaertner :

You can see the html output of fpdoc when pressing F1 on an identifier.

It will pop up an error message that there is no help available although I have created fpdoc help entries and the fpdoc editor shows the entry when i am on this identifier. For classes that are defined in the LCL it will open the web browser an fetch the documentation online.

You can install lhelp for an offline help viewer.

Trying this now.

2010/7/23 Bernd :

> You can install lhelp for an offline help viewer. Trying this now.

This will give me a nice chm viewer if i additionally download the chm files for LCL, FCL and RTL (the scripts in docs/html fail with some file not found messages) but it still won't show me the contents of my fpdoc file. There is a button missing: "show in help viewer" and the F1 key should first look for available fpdoc before it does anything else.

The fpdoc thing seems not yet usable to me. it fails to find classes like for example TObject which are defined in some include files and that seem to have been manually moved into other fpdoc files because there seems to exist generated documentation for them in the online help and the chm.

This is exactly the kind of problem that I mentioned earlier. Maintaining code and documentation in separate files will always cause them to be out of sync sooner or later and will be a never ending source of problems and frustration. Even more so if the tools to use them are not anywhere near usable yet.

2010/7/23 Martin :

It seems you misunderstood me too. There are two types of comments, the ones that explain the "how" or the "what" and the ones that explain the "why".

The "what" and "how" can be left away if the code is clearly written and identifiers have speaking names. It is visible in right in the editor window by simply lloking at the code *what* it does and also *how* it does this.

The comments that are needed are the *why*, these explain things that are not visible when looking at the code that is in front of you. The example with the AVL tree is not very good. If AVL trees were used everywhere all over the place then there would no comment be needed at all, if it was implemented to solve one specific problem then maybe something like

(*Implements an AVL tree*)
TAVLTreeNode = class
  FLeft, FRight, FParent: TAvlNode;
  FBalance: Integer;
end;

and somewhere else:

(*This tree holds the <dont know>. the basic idea is that every node represents a <dont know> and we also store the <dont know> so that we can then easily <dont know> This tree is created by <dont know> immediately after <dont know> and used to <dont know> by <dont know>*)
TSynTextFoldAVLNodeData = Class(TAVLTreeNode)

  public
  [...]

As soon as the declaration is bigger than 1 page on the screen it should have such a comment that describes in a few words what it is meant for and things. If it is a central cornerstone of the architecture it would not hurt to describe the purpose and the intention even more verbose.

This is all I am asking for in all these classses that serve only very specific purposes and are used in a very special way and sometimes also in not very obvious containment would
greatly help to be able to quickly see where and for what purpose this class might be used. If only every class had such a short description mentioning its purpose and the place and the role it will have at runtime, where its instances will live and how long. It would be so much easier to understand the whole picture and I cannot imagine that anybody would ever be annoyed by this.

Don't document what is there (this is obvious by scrulling down and reading the code) document why it is there and from where and how it its used.

Also I have noticed that in many of the rare occasions where a class has a documentation like here:

{ TSynTextFoldAVLTree
Nodes in the tree cover the folded lines only
the cfCollapsed line at the start of a fold, is *not* part of a node. RemoveFoldForline has special precaution for this. }

TSynTextFoldAVLTree = class

It is used the wrong way. The empty line will make make the comment effectively invisible for the hint- or help system and also there are many comments that consist only of the name of the class that follows afterwards:

{ TSynFoldNodeInfoHelper }

TSynFoldNodeInfoHelper = class

SUCH comments are indeed annoying because they are not only redundant, they are completely unnecessary. The abuse of comments as some kind of "bookmarks" or separators to be able to quickly scroll until the next green line appears and something ends and something else starts serves no purpose. Therefore better tools exist. Comments are meant to *explain* things, not to draw horizontal lines into the code that are only meant as separators and to be visible during fast scrolling from 2 meters distance.

"why" might not be the best word to describe. "purpose" may be closer, but doesn't matter.

Well but again, the same documentation can be done in any way or place.

We are not talking about the fact that it is currently missing only where to place it.

Also to whom to I write the comment?
1) A person who is going to use this class in it's own code?
2) A person who is going to modify the code in the unit of that code (extend/change/refactor/fix the class...)

The first person is not normally having to look at the source. In fact the first person could just have a ppu file, and no source which case the first person would rely on the help being in an external file

For the 2nd person, I can find equally good argomens for both solutions. It's simply a matter of personal taste.

"purpose" + "where" + "how long" ....

That again is very quickly growing to more than a few lines of comment. If properly documented an external help, providing linked references, index/overview, etc can be much more powerful than a comment.

Of course a "2 line hint" in a comment, is much better than a none existing "2 page explanation" in an external file....

And of course creating an external file, to hold a 3 word explanation *rather than having 3 words in a comment) is not very practical either....

----
Anyway for your own classes, you can do as you are pleased => and the IDE does show it in the hints => so no code such as the LCL (or the example you picked from SynEdit) it is down to who ever writes the code or docs, to decide where to put them. And as far as I can see, the bigger matter is not where, but that partially they are missing completely...

Martin

----
p.s:
As for the example you picked ( TSynTextFoldAVLNodeData): you will have noticed that there are comments (not implying anything about the content/quality) of them.
As for an explanation of the whole class: I would have simply thought that finding an AVLNode, in a FoldTree, anyone looking at it would conclude it contains data about one piece of folded code (eg, fold 10 lines starting at line 255).

Never noticed that, as I didnt rely on this.
I simply find the code itself more readable if a multi-line comment is separated by a line from the class below.

Then again, in *this* *case* this comment is for an internally only used class, usable only for people working inside this unit. So you read it as you explore the source, rather than in the hint.

They are automatically created by codetools...

Martin

You can turn the creation off.

It is a todo to search for those comments for the hint.

Mattias

2010/7/24 Martin :

?As for an explanation of the whole class: I would have simply thought that finding an AVLNode, in a FoldTree, anyone looking at it would conclude it contains data about one piece of folded code (eg, fold 10 lines starting at line 255).

You came up with the AVL tree and the only place where AVL is mentioned (I did a search on identifiers) anywhere in the IDE was the code folding thing.

I have never written a folding text editor in my whole life, so I have no Idea what possible alternatives have proven to be useful for implementing such a thing nor can I spontanuosly imagine how a tree structure (why/how is it a tree?) might be useful here.

The audience for code and comments that make up the application itself is of course the person who comes to the project and wants to start working on its implementation. I don't know whether the Lazarus Project wants to attract new developers or not. If this is the intention then there should be documents that describe what concepts are used and how all the parts play together. And for you as a programmer who knows it all already would be easiest to write a few lines for every class and maybe also a few lines for every unit or about the architecture of a bigger part as a whole.

Who else but *you* or those who wrote the code should be able to write this? If you dont do it who else should do it? This should IMHO have highest priority: Stop all coding and start documenting what you have done so far until there is enough prose to read to have an overview of all the parts of the IDE and how they play together.

Let me repeat it: The audience for documentation is people who have less knowledge about the architecture than you and also new programmers who might be experienced and might *know* exactly what an AVL tree is but still have no clue *why* the hell there was such a tree chosen for exactly this problem (what problem?) and how exactly it is utilized *without* sitting down for a few hours studying and debugging the code until they find out what could have been written in 3 or 4 simple sentences by the initial developer.

The code is in large parts a completely undocumented mess! It is absolutely no fun to read it!

You can either chose to keep it a 3 man show of only a handful of people by not sharing any of the secret knowledge with ordinary mortals like me or you could chose to finally start *documenting* what you have done already in a way that is commonly agreed upon amongst developers how such complicated code should be documented and people will be able to learn how all the many parts of the IDE are working together and new developers might be able to join to the project.

2010/7/24 Martin :

Then this should be removed and the codetools should be fixed to not do such things. Some people are already annoyed by useful comments that contain helpful information so the comments that only mention the name of the identifier that follows might be even more annoying.

2010/7/24 Martin :

Then again, in *this* *case* this comment is for an internally only used class, usable only for people working inside this unit. So you read it as you explore the source, rather than in the hint.

All of what I am saying is for people working on the internal code.

The hint is still useful when I am at a place where it is used and not where it is declared. This unit is 3700 lines of code, I can either jump to the declaration to see what it is/does (then i have to jump back again) or I could just hover my mouse over the identifier and have the most useful information in a little hint window.

The reason it is not reliable in Lazarus is that comments are not used and for some strange reason the programmers find documentation is completely useless (for themselves) because everybody is writing only for himself and the compiler and for nobody else and accidentally reading a block comment above a class definition with detailed information that is already known to the programmer (because he once wrote it), reading his own writing again would create a distraction so big that further programming would become almost impossible.

> They are automatically created by codetools... Then this should be removed

No, AFAICR this is Delphi compatible.
And I like it, reason enough to keep it.

R.

or I could just hover my mouse over the identifier and have the most useful information in a little hint window.

Don't use the evil M-word when talking about an editor, which is operated via key strokes. :)

Can you somehow proof, that you are not Graeme?
No offence ment.

Just relax a bit before writing mails. This is not the place to accuse people that *actually write code* of doing something wrong. I can understand some of your frustations but other people found their way around the code. The documentation is lacking or not easy to use, but that is pretty standard for an open source project. Just start coding and if you have problems to understand something you can ask on the devel mailing list. No reason to try to convice everyone on the user list to use your comment style.

Disclaimer: I am not a Lazarus developer just my personal opinion.

R.

Because comparing the cost of computing ("Big O" [1]) for inserting, deleting or looking up information is reasonable low (and memory footprint acceptable)

Say you store a flag on each line: visible/invisible: insert/delete => fast O(1)
lookup => slow O(n) // n= amount of line
=> e.g computing the amount of folds before the 1.000.000 line => loop through all of the lines

avl tree all operation a O(log n) //n amount of currently folded areas) (A bit slower in the IDE , due to nesting)
=> e.g computing the amount of folds before the 1.000.000 line (assuming each line has one fold) => go through 20 nodes [and if there are only 100 folded sections, in the first 1000000 lines => go through 7 nodes]

From the examples you can see the difference in time needed to compute certain information

[1] http://en.wikipedia.org/wiki/Big_O_notation

----
The above explanation of course is only meaningful if you already know about such structures and algorithms and big o ......

Tto proper document it, is a huge amount of work...

Now we switch topic => there is no doubt that docs are needed. (And yes new contributors are always wanted, so this underlines the point)

But a new contributor can equally read comment or fpdoc. Assuming he uses the IDE, and it's setup correctly, both will show up as hints.

Half agreed, an AVL tree is well known, and if you do not => wikipedia => no need to put that in code.

why it was chosen may not even matter => it was, there are 100 of ways of doing it, one was chosen.
And anyway => explaining this, will take more than a feew lines fitting into a comment

The code is in large parts a completely undocumented mess! It is absolutely no fun to read it!

Nothing to do, with the question comment or fpdoc
but as above, no disagreement on the need of docs.

And for as long as they are absence => ask on this mail list, and if anyone knows you will be answered

I agree, and yet unfortunately it want change much (not immediately anyway)

And there are plenty of other mailthreads 100 of mails explaining the need, and whys, and pro and contras of various ideas/needs => and even after a 100 mails nothing changed.

Everyone know, and knew the need for docs. Some has been done, others has not. Being reminded of this need, doesn't change this. I have started a few bits on synedit, very little yet. Simply because most of the time I rather write new code => I do it in my spare time, I don't get paid, I like to do, what I feel I want to do most....

And when it comes to docs, most of them are about, how to use it in your app => and there are some docs for that, but the next issue is they are hard to find. Lot of it is on the wiki.

It's a catch 22 => I agree with you, yet I aint going to do anything (well, not any more than I would anyway do)

------
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

You can turn the auto creating of class headers off in the options.

There are many different coding styles and so there are many different commenting styles.

See here:
http://wiki.lazarus.freepascal.org/Lazarus_IDE_Tools#Hints_from_comments

Note:
A class header is the comment in front starting with the class name. There can be code in between. For example:

type
  { TMyClass ... }
  TMyEvent = procedure of object;
  TMyClass = class
    ...
    property MyEvent: TMyEvent ...
  end;

Some people use the class header for scrolling or for beautification, others add some text. It is up to the programmer/boss to decide what fits best.

Mattias

Well, I use it extensively.

The only pity is that I cannot specify its form.

Michael

What would you specify?

Mattias

> or I could just hover my mouse over the identifier and > have the most useful information in a little hint window. Don't use the evil M-word when talking about an editor, which is operated via key strokes. :)

It depends on what you really do: write or read (browse) code. You also don't use your computer to compute numbers, most of the time. The original German name for such machines was "Elektronengehirn", i.e. electronic brain ;-)

DoDi

A template like the others. | stands for the class identifier. I guess you'd need 2 templates. One for the interface, one for the implementation. My main interest is for the implementation one.

Michael.

Graeme (I think it was him) had once an quite good idea about that => make it {%region TSomeClass } / but that needs the closing tag too

Bernd wrote:

Much stuff that appeared on a single line, with occasional missing spaces. If it's difficult to write it should be difficult to read. Here endeth the rant :-)

I wonder if I could ask a question that follows on from Bernd's sentiment. He points out that the IDE will pick up a comment /before/ a declaration, but for getting on for 30 years I've been putting comments immediately /after/ and that includes the positioning of a unit summary. What's more I've been writing comments where every line is terminated ("Sloane style") rather than having a brace at the start of each comment and one at the end, and I still favour (* *) because of years spent using Modula-2.

Is there a Lazarus Style Guide somewhere, that deals with how best to format code so that the IDE can exploit it, that deals with using fpdoc or something similar for ones own projects, and that possibly even deals with writing help files (of some suitable format)?

Not sure about if/where the various "IDE can read this commnet"...

But a comment at the end of the *same* line, is also recognized.

procedure Foo; // Does something real important

Use the < sign at the beginning.

  a=1;
  //< Comment for a
  b=2;
  //< Comment for b

See here
http://wiki.lazarus.freepascal.org/Lazarus_IDE_Tools#Comments_shown_in_the_hint

What's more I've been writing comments where every line is terminated ("Sloane style") rather than having a brace at the start of each comment and one at the end, and I still favour (* *) because of years spent using Modula-2.

All three comment formats are supported by the IDE:
//
{}
(**)

Is there a Lazarus Style Guide somewhere, that deals with how best to format code so that the IDE can exploit it,

For the hint stuff, see the above link.
AFAIK the todo comments are not documented yet.

that deals with using fpdoc or something similar for ones own projects, and that possibly even deals with writing help files (of some suitable format)?

About fpdoc
http://wiki.lazarus.freepascal.org/FPDoc_Editor

For the rest use your search engine.

Mattias

I'm in the same boat (35+ years). Comments are always immediately after instead of before. Among other things this helps ensure the comment is not lost when the code is moved since it is located *within* the unit/procedure/function. I sure hope any further automated support will be able to handle this style.

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 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:

(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?

I changed the subject, otherwise it may not get noted by whoever has the answer (since the old subject was just about to develop into an endless thread...)
My expertise mainly goes to SynEdit, so this may have to be answered by someone else.

Despite this not being code familiar to me, I had a quick look through the stuff you already found:
I am sure someone with more knowledge will comment on it, but until then:

 From
ide/main.pp line 15060
procedure TMainIDE.OnSrcNotebookShowHintForSource(SrcEdit:
TSourceEditor; ClientPos: TPoint; CaretPos: TPoint);
TIDEHelpManager(HelpBoss).GetHintForSourcePosition(ActiveUnitInfo.Filename,
                                           CaretPos,BaseURL,SmartHintStr);
HelpBoss is a gobal variable in the Unit HeplManager, it seems to be the
best point to start getting contnet from.
- BaseURL,SmartHintStr are out param
- you don't need ActiveUnitInfo, only the filename.
   you can get a unitinfo, if you have the editor: AnUnitInfo :=
Project1.UnitWithEditorComponent(AEditor);
   // project1, is a global var too in Unit Project
   // project1 is generally a good point to get the unitinfo from

So (full-)filename and caretpos, and you can get content

----

As for creating the hint window, not sure what the easiest, best way is, but there is an example here:
ide\sourceeditor.pp line 6200
procedure TSourceNotebook.ActivateHint(const ScreenPos: TPoint; const BaseURL, TheHint: string);

It's a few lines only.

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I just did some experiments with CodeHelpBoss.GetHTMLHint() and it almost works, it does not crash and I could see hint windows containing the fpdoc entries (with html tags) and sometimes (?) the comments.

I will now try to do it with
TIDEHelpManager(HelpBoss).GetHintForSourcePosition() and see whether this also works.

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iD8DBQFMS2U1xT6R4jlFoh0RAuomAJ9f4ULq+NS0yqt35xjeLT9tWNR9bgCfb07x LXS9XWYdUr+RvH0kz8hcTTI=
=F1Ry
-----END PGP SIGNATURE-----

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I will now try to do it with TIDEHelpManager(HelpBoss).GetHintForSourcePosition() and see whether this also works.

OK, this works. The code is even easier with using the above function. The problem with not displaying the comments was because I had to click "rescan" in the code browser after inserting comments in teh code to test it.

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iD8DBQFMS2goxT6R4jlFoh0RAjSpAJ9s1frke8psVotuAGrivA/Fc9fVJgCgqdd7 Jxqzw+8H+qWIZJnpBil9y78=
=h60Q
-----END PGP SIGNATURE-----

What is the problem? How to reproduce?

OK, this works. The code is even easier with using the above function. The problem with not displaying the comments was because I had to click "rescan" in the code browser after inserting comments in teh code to test it.

Mattias

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Mattias Gaertner wrote

What is the problem? How to reproduce?

It seems to work now. I can display a THindWindow in the code browser containing the information from fpdoc and the comments.

The only thing i still don't understand is how to deal with the HTML tags in the fpdoc. The very same THintWindow window that is created exactly with the same data in the source editor will not show the HTML tags but I cannot find anything in the existing code that would strip the tags and I also cannot find any way to make
TIDEHelpManager.GetHintForSourcePosition() return plaintext instead of HTML.

How does the editor version of the hint window get rid of the HTML tags? -----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iD8DBQFMS3fmxT6R4jlFoh0RAmGxAJ98dOy8TzCiFxiReczCVZNlntEv0QCfSADS hEJiW89OpisaQhCfAa0exWY=
=iqwK
-----END PGP SIGNATURE-----

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Bernd Kreuss wrote

Mattias Gaertner wrote: > What is the problem? How to reproduce? It seems to work now.

Not really. it works only for classes, not for methods, It will display the method as if it were a function and does not know that it belongs to a class.

Why does TIDEHelpManager.GetHintForSourcePosition() not recognize that it is a method of an object? in the source editor the very same function will give the correct hint, even when pointed at the forward declaration in the class declaration. What am I doing wrong?
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iD8DBQFMS3skxT6R4jlFoh0RAoRGAKDdSFP1HPLHNKz3mwUlT7DRoPGUFgCeMQfH DVDj7OLziXdUm1ZpZ/bfnKk=
=DxMv
-----END PGP SIGNATURE-----

With "code browser" you mean View / Code Browser, don't you?

First of all: fpdoc returns xml tags, not html tags. Converting is a todo.
The idea is this:
The fpdoc and the comments are fetched, put together and some html is created, including links. Then the viewer control shows the html. At the moment there are two viewer controls. One simple label, that simply strips the html. And one from turbopoweripro package. When you install the package it replaces the label.

Mattias

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Mattias Gaertner wrote:
One simple label, that simply

strips the html. And one from turbopoweripro package. When you install the package it replaces the label.

I have thought it was THintWindow, but this one does not seem to be able to strip the tags and also will not be replaced with the turbopoweripro one.

Which one should I use? where is the code that initializes this window? I cant find it and in TSourceNotebook.ActivateHint it does:

FHintWindow:=THintWindow.Create(Self);

I am doing the same but wont get the label that will strip the tags. It looks exactly the same but it simply wont strip the tags and also not be replaced by turbopoweripro. Where is the label that I really want? -----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iD8DBQFMS4SjxT6R4jlFoh0RAipWAKCSeGFJTzCD9hb6rr3ndjqcPX20OACeJi3h y5/raVhWzSgjW7xcu+I+06Q=
=rOgv
-----END PGP SIGNATURE-----

I note discussion elsewhere in the thread about using fpdoc in preference to embedded comments. I think it's worth noting that at some point in the future code might be read by somebody who only has the source and doesn't have the Lazarus IDE etc., in much the same way that Lazarus/FPC developers have to refer to kernel and library header files written for C/C++.

Thanks, I was reading it. Would be nice if the no-space restriction could be relaxed. If every line of a comment block is terminated does the IDE pick up all of them and does each one need < at the start?

All three comment formats are supported by the IDE: // {} (**)

Does this include manually-inserted TODOs? I'd also note- although it's not really relevant for documentation- that braces appear to be favoured for directives: (*$MACRO didn't work when I tried it a few months ago.

fpdoc has many output formats and the html output is put online. fpdoc is a command line utility, not part of the Lazarus IDE. Several people are working on offline viewers.

Mattias

Maybe eventually a per unit flag can be set to relax this.

If every line of a comment block is terminated does the IDE pick up all of them and does each one need < at the start?

You mean:

a=1;
//< Comment for a
//< another comment for a

The todo list supports all three styles.

I'd also note- although it's not really relevant for documentation- that braces appear to be favoured for directives: (*$MACRO didn't work when I tried it a few months ago.

Yes. That's a fpc decision.

Mattias

It's a THintWindow, but with a control inside.
See TSourceNotebook.ActivateHint how to use it.
Code is in helpmanager.pas

Mattias

Mattias Gaertner wrote

It's a THintWindow, but with a control inside. See TSourceNotebook.ActivateHint how to use it. Code is in helpmanager.pas

Ok, I think I found the reason and have a new question:

in TIDEHelpManager.CreateHint (in helpmanager.pas at line 1265)

which will be called somewhere later during the hint creation there is the following:

  IsHTML:=SysUtils.CompareText(copy(TheHint,1,6),'<HTML>')=0;

I did not have the html tag at the first position so this method thought it was plaintext and used a plaintext label. But the same thing happens also whenever you are debugging an application and then create a hint. There will be information from the debugger at the fist part of TheHint and the normal hint text (with the tags) follows at the end and so it will not recognize the HTML and use a plaintext label. Debug an application and hover the mouse over an identifier with fpdoc and you will see ugly tags in the hint.

I understand that a HTML control would not be able to interpret the line breaks in the debugger output and also in the debugger output there could be html tags as variable contents so they could not just easily be all stripped from the text, but I think there still should be some elegant way found to handle or avoid this mixed plaintext/html situation. Maybe TIDEHelpManager.GetHintForSourcePosition() should be given the ability to automatically return a stripped version whenever the debugger is running or alternatively always format the debugger output or even *anything* that goes into such hints *always* into nice and proper html after escaping all occurrences of < and > with htmlentities and then always use the HTML label.

OK I have the fancy fpdoc and comment hints working for the codebrowser too.

I will clean it all up now and prepare a patch. It is not much code, simpler than I have initially thought.

Bernd Kreuss wrote

OK I have the fancy fpdoc and comment hints working for the codebrowser too. I will clean it all up now and prepare a patch. It is not much code, simpler than I have initially thought.

OK, here is the patch. It works against current svn trunk and will enable the same sot of mouse-over hints that exist in the source editor also in the code browser.

Please somebody review it and tell me if this is acceptable.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: better-hints-codebrowser.diff
Type: text/x-diff
Size: 4761 bytes
Desc: not available
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20100725/bed1db45/attachment.bin>

Please revert and throw away the previous patch and use this one instead:

-------------- next part --------------
A non-text attachment was scrubbed...
Name: better-hints-codebrowser-1.diff
Type: text/x-diff
Size: 4880 bytes
Desc: not available
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20100725/449c29e4/attachment-0001.bin>

Hi!

It might be better to create a "feature request" for this in the Bugtracker, because the patch might be forgotten here. Also some people might already ignore this monster thread :P

Regards,
Sven

Actually I meant

a=1;
(*< First line of a long block           *)
(*  of comments arranged "Sloane-style". *)

+ case LowerCase(LeftStr(TVNode.Text, 7)) of + 'functio' : CodePos.X += 9;

Does that work in fpc 2.4.2?

Mattias

Mattias Gaertner wrote

> + case LowerCase(LeftStr(TVNode.Text, 7)) of > + 'functio' : CodePos.X += 9; Does that work in fpc 2.4.2?

Haven't tried it. Why should it not work? What was missing in 2.4.2?

Actually I was hoping somebody would come up with a better solution for this rather ugly hack (at least I don't like it myself). But theoretically it should always work. The text in the nodes of the tree view *always* starts with function, procedure, etc., never directly with an identifier, additional spaces are removed. and the code position always points to the beginning of the declaration. The only declarations in the actual code that do *not* start with an identifier should be class procedure, procedure, class function, function, constructor, destructor and property and nothing else so from the logic it should work.

Should it fail for whatever reason (the above reasoning might be wrong) then it simply falls back to producing the old hint that has always been there.

How would you then separate comments pertaining to the following item?

DoDi

Bernd Kreuss wrote

Mattias Gaertner wrote: >> + case LowerCase(LeftStr(TVNode.Text, 7)) of >> + 'functio' : CodePos.X += 9; > Does that work in fpc 2.4.2?

HA! It took a while until It finally sunk in. It seems I have used all these high level scripting languages for too long, so I take things for granted that are not always granted everywhere ;-)

I will change it so it will work with older compilers also. Current FPC trunk seems to allow case of string without any problems (which is a nice feature btw.), so I didn't even notice what I was doing.

By the fact that there's a declaration between them. Anybody who isn't consistent in his commenting or coding style deserves all the trouble he gets, and in general anybody maintaining a unit should try to conform to the originator's style.

Having said that I stress that I'm not holding up my own style as a paragon of excellence, and I haven't a clue how many other people use something similar. Which I why I wrote

> Is there a Lazarus Style Guide somewhere, that deals with how best to > format code so that the IDE can exploit it, that deals with using > fpdoc or something similar for ones own projects, and that possibly > even deals with writing help files (of some suitable format)?

and have never dreamed of saying that the Lazarus developers should cater to my quirks and eccentricities.

Not when the second one is a comment on the *next* declaration.

Anybody who isn't consistent in his commenting or coding style deserves all the trouble he gets, and in general anybody maintaining a unit should try to conform to the originator's style.

I've seen enough mixes of styles, when I fixed the comment handling in PasDoc.

DoDi