Re: [fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?
On Thu, Jul 18, 2013 at 10:41 PM, Kenneth Cochran kenneth.coch...@gmail.com wrote: Now I'm trying to track down how the source editor invokes FPDoc support when you hover over an identifier. A search for FPDoc in the source turned up the CodeHelp unit. Anyone know if I'm on the right track? Yes. See also : TMainIDE.OIChangedTimerTimer in unit ide/main. It updates the Object Inspector info box. Juha ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?
On Wed, Jul 17, 2013 at 4:24 PM, Kenneth Cochran kenneth.coch...@gmail.comwrote: On Wed, Jul 17, 2013 at 3:53 AM, Mattias Gaertner nc-gaert...@netcologne.de wrote: Do you mean hovering over the component in the designer? At the moment the hint shows only the caption and some common values. It could be extended to show the help for the variable. Feel free to create a feature request. I think he's referring to hovering over the component icon on the component pallet. Right now the tool tip shows the class name and the unit it is defined in. I think he wants it extended to include a description of the component's purpose. So hovering over the TButton icon would display: TButton (StdCtrls) A push button control. I'm all for making components more discover-able but I don't think increasing the memory footprint of every control with a comment or description field is the right solution. Using the FPDoc info already available would be a good solution. I prefer this to the JavaDoc/XMLDoc style comments in the source. I'm willing to give it a go but I've never done anything extensive with either FPDoc or the IDE internals. Anyone have a ballpark guess as to how much effort would it take to extend the tooltip for the component pallet to display the short tag from the FPDoc info? ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?
On Thu, Jul 18, 2013 at 6:26 PM, Kenneth Cochran kenneth.coch...@gmail.com wrote: Anyone have a ballpark guess as to how much effort would it take to extend the tooltip for the component pallet to display the short tag from the FPDoc info? The hint is set in unit ide/ComponentPalette, line 744 in Lazarus trunk. I don't have details for getting the FPDoc info but you can study the code yourself. It is used for example in the Object Inspector's Information Box below the properties. I don't think the feature requires much code once you have figured out where to get the needed data. This is typical in a big project. A commit with only few lines of code has required many hours of studying the existing code. May the source be with you! :) Juha ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?
On Thu, Jul 18, 2013 at 2:22 PM, Juha Manninen juha.mannine...@gmail.comwrote: On Thu, Jul 18, 2013 at 6:26 PM, Kenneth Cochran kenneth.coch...@gmail.com wrote: Anyone have a ballpark guess as to how much effort would it take to extend the tooltip for the component pallet to display the short tag from the FPDoc info? The hint is set in unit ide/ComponentPalette, line 744 in Lazarus trunk. I don't have details for getting the FPDoc info but you can study the code yourself. It is used for example in the Object Inspector's Information Box below the properties. I don't think the feature requires much code once you have figured out where to get the needed data. This is typical in a big project. A commit with only few lines of code has required many hours of studying the existing code. Yea, I found TComponentPalette.UpdateNotebookButtons on my own in a round about way. I set a breakpoint in TControl.SetHint and launched an instance of the IDE with the debugger attached. After a half dozen hits I was into the pallet speedbuttons and checked the call stack. Now I'm trying to track down how the source editor invokes FPDoc support when you hover over an identifier. A search for FPDoc in the source turned up the CodeHelp unit. Anyone know if I'm on the right track? ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?
On Tue, 16 Jul 2013 22:56:33 +0100 vfclists . vfcli...@gmail.com wrote: [...] I have 2 main concerns here, a comment for the component itself which is not particularly important and a comment for the component when I add it to a form or data module. When I create a method I can add a comment to the method. If I create a component in code, I can label that section of code, but if I drag and drop a component from the palette onto the form what option do I have? Descriptive variable and component names have a habit of getting too long. You can comment the variable. For example: Edit1: TEdit; // Now, that's a great Name It is hardly for the end users sake unless the enduser is a programmer. I just need something to help when working in the IDE, eg hovering over a component and seeing the comment in addition to what is current displayed. Do you mean hovering over the component in the designer? At the moment the hint shows only the caption and some common values. It could be extended to show the help for the variable. Feel free to create a feature request. Mattias ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?
On 17/07/13 00:56, vfclists . wrote: I completely disagree. It is the code that is the primary expression of intent not the comments. This is mainly accomplished through sensible identifier naming. I perfectly agree, a well formed name is worth a thousand words, in this context. Comments exist to compensate for a developer's inability to express intent through the code and IMHO should be reserved for this sole purpose. In most cases you should be able to look at a function signature and know exactly what that function's intent is. Likewise you should be able to tell the intent of a class by its name and the names of its public/published members. This is, at least, what I strive for in my own code. Bob Martin's Clean Code dedicates the entire 4th chapter to the discussion of comments and make some very compelling arguments for limiting their use. That's true, in principle; thou' you shall look at the comments also like: you cannot express the meaning and whole role of a function by its name (unless you want to couple wikipedia, of course), especially where you made some tricks that _today_ they look obvious because you're in the thing, but _tomorrow_ they might not. I still endlessly thank myself for having put some of these comments somewhere in my code, some of 15 years ago... they helped me make the migration from DOS to Linux a little less hurting ;-) Of course, we're talking about good and wise use of comments, which is, IMHO, still an art. Just my 2c on this, Al. ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?
On 17/07/13 00:56, vfclists . wrote: It is hardly for the end users sake unless the enduser is a programmer. we're talking about programming languages here, so that... whoever else shall an end user of a development tool/library be?!?!?!? X_X ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?
On Wed, Jul 17, 2013 at 3:53 AM, Mattias Gaertner nc-gaert...@netcologne.de wrote: Do you mean hovering over the component in the designer? At the moment the hint shows only the caption and some common values. It could be extended to show the help for the variable. Feel free to create a feature request. I think he's referring to hovering over the component icon on the component pallet. Right now the tool tip shows the class name and the unit it is defined in. I think he wants it extended to include a description of the component's purpose. So hovering over the TButton icon would display: TButton (StdCtrls) A push button control. ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?
On 15 July 2013 22:58, Kenneth Cochran kenneth.coch...@gmail.com wrote: I completely disagree. It is the code that is the primary expression of intent not the comments. This is mainly accomplished through sensible identifier naming. Comments exist to compensate for a developer's inability to express intent through the code and IMHO should be reserved for this sole purpose. In most cases you should be able to look at a function signature and know exactly what that function's intent is. Likewise you should be able to tell the intent of a class by its name and the names of its public/published members. This is, at least, what I strive for in my own code. Bob Martin's Clean Code dedicates the entire 4th chapter to the discussion of comments and make some very compelling arguments for limiting their use. ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal I have 2 main concerns here, a comment for the component itself which is not particularly important and a comment for the component when I add it to a form or data module. When I create a method I can add a comment to the method. If I create a component in code, I can label that section of code, but if I drag and drop a component from the palette onto the form what option do I have? Descriptive variable and component names have a habit of getting too long. It is hardly for the end users sake unless the enduser is a programmer. I just need something to help when working in the IDE, eg hovering over a component and seeing the comment in addition to what is current displayed. -- Frank Church === http://devblog.brahmancreations.com ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?
On 7/16/2013 17:56, vfclists . wrote: I have 2 main concerns here, a comment for the component itself which is not particularly important and a comment for the component when I add it to a form or data module. When I create a method I can add a comment to the method. If I create a component in code, I can label that section of code, but if I drag and drop a component from the palette onto the form what option do I have? if one doesn't know what a component does when they drag it from the pallet, shouldn't they have the docs open which explain that component? Descriptive variable and component names have a habit of getting too long. agreed... i hate typing in 10+ character var or routine names... especially since i'm still working on trying to move from the old DOS TP6 environment ;) It is hardly for the end users sake unless the enduser is a programmer. I just need something to help when working in the IDE, eg hovering over a component and seeing the comment in addition to what is current displayed. i feel ya, man... i feel ya O:) -- NOTE: No off-list assistance is given without prior approval. Please keep mailing list traffic on the list unless private contact is specifically requested and granted. ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
[fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?
On 11 July 2013 23:07, Benito van der Zander ben...@benibela.de wrote: Annotations like in Java would be nice... On 07/11/2013 10:22 PM, vfclists . wrote: Should TObject or TComponent have a Comment property? I think they should. One for the design itself and one for describing the usage at design or runtime. Smalltalk has it. Consider it a version of the Hint property but for the developer -- Frank Church === http://devblog.brahmancreations.com -- ___ Lazarus mailing listLazarus@lists.lazarus.freepascal.orghttp://lists.lazarus.freepascal.org/mailman/listinfo/lazarus -- ___ Lazarus mailing list laza...@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus This attitude which exists in the Pascal community needs to end. I say Pascal not FreePascal because when I examine a lot of free Delphi libraries I see the same thing. Lots and lots of code and not a comment in sight. It makes stuff needlessly difficult. The simple fact is documentation is never going to happen because no one has time to create it with separate tools, not even the people writing the code themselves. Coding time is the best time for documentation because that is when the intent of the code is clear and fresh in the developers mind, and incurs minimal additional cost. After all it takes barely a minute or two to describe a function, and the same parsing tools compiling the code can pull out the comments and create documentation stubs if there is a need to flesh them out further, eg with examples etc Even a lot of the funded open source libraries don't have the resources to create proper documentation. If you take Delphi for instance, since Turbo Pascal, Delphi 7 etc the quality of documentation has gone down and these are companies that are well funded. Instead of doing the simple thing a purist attitude has been adopted which never does anyone any good. It is time developers learn to treat other developers as consumers not people who are supposed to RTFC or RTFM. Developers are people who are supposed to put parts together just by examining the function parameters and the function descriptions rather than wade through loads of procedure definitions and sample code full of similar sounding and confusing names. Enough digression - if considered carefully a comment about the purpose of an object belongs in the object definition itself. Why should interrogation about an object's purpose be handled by a whole subsystem of code which has precisely nothing to do with the object, ie the operating system, a help displaying program, a filename which is the help document, as well as a search string which is the object's name? Multiply that by the variety of help displaying programs for each operating system, then by the number of operating systems available then you can see how ridiculous the whole concept is. Just bureaucracy piled on bureaucracy and attachment to ill thought out convention and tradition. There is never a direct link between an object and the help display programs available on the operating system. There is a totally insane disconnect here. The Smalltalk guys got it right. There can be an options to strip the comments out in the final deliverable just like the debugging information. -- Frank Church === http://devblog.brahmancreations.com ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?
On Fri, 12 Jul 2013 07:07:05 +0100 vfclists . vfcli...@gmail.com wrote: This attitude which exists in the Pascal community needs to end. Not really. R. ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?
Enough digression - if considered carefully a comment about the purpose of an object belongs in the object definition itself. I use Pasdoc for that On 07/12/2013 08:07 AM, vfclists . wrote: On 11 July 2013 23:07, Benito van der Zander ben...@benibela.de mailto:ben...@benibela.de wrote: Annotations like in Java would be nice... On 07/11/2013 10:22 PM, vfclists . wrote: Should TObject or TComponent have a Comment property? I think they should. One for the design itself and one for describing the usage at design or runtime. Smalltalk has it. Consider it a version of the Hint property but for the developer -- Frank Church === http://devblog.brahmancreations.com -- ___ Lazarus mailing list laza...@lists.lazarus.freepascal.org mailto:laza...@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus -- ___ Lazarus mailing list laza...@lists.lazarus.freepascal.org mailto:laza...@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus This attitude which exists in the Pascal community needs to end. I say Pascal not FreePascal because when I examine a lot of free Delphi libraries I see the same thing. Lots and lots of code and not a comment in sight. It makes stuff needlessly difficult. The simple fact is documentation is never going to happen because no one has time to create it with separate tools, not even the people writing the code themselves. Coding time is the best time for documentation because that is when the intent of the code is clear and fresh in the developers mind, and incurs minimal additional cost. After all it takes barely a minute or two to describe a function, and the same parsing tools compiling the code can pull out the comments and create documentation stubs if there is a need to flesh them out further, eg with examples etc Even a lot of the funded open source libraries don't have the resources to create proper documentation. If you take Delphi for instance, since Turbo Pascal, Delphi 7 etc the quality of documentation has gone down and these are companies that are well funded. Instead of doing the simple thing a purist attitude has been adopted which never does anyone any good. It is time developers learn to treat other developers as consumers not people who are supposed to RTFC or RTFM. Developers are people who are supposed to put parts together just by examining the function parameters and the function descriptions rather than wade through loads of procedure definitions and sample code full of similar sounding and confusing names. Enough digression - if considered carefully a comment about the purpose of an object belongs in the object definition itself. Why should interrogation about an object's purpose be handled by a whole subsystem of code which has precisely nothing to do with the object, ie the operating system, a help displaying program, a filename which is the help document, as well as a search string which is the object's name? Multiply that by the variety of help displaying programs for each operating system, then by the number of operating systems available then you can see how ridiculous the whole concept is. Just bureaucracy piled on bureaucracy and attachment to ill thought out convention and tradition. There is never a direct link between an object and the help display programs available on the operating system. There is a totally insane disconnect here. The Smalltalk guys got it right. There can be an options to strip the comments out in the final deliverable just like the debugging information. -- Frank Church === http://devblog.brahmancreations.com ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?
On 2013-07-12 07:07, vfclists . wrote: Coding time is the best time for documentation because that is when the intent of the code is clear and fresh in the developers mind, and incurs minimal additional cost. And you just said it yourself. If the developer of the code doesn't even have the time to add code comments in his code, why do you think having an Comment property would make it any better? It will not - the developer would still not have any time. You don't need seperate tools to create documentation - code comments can serve as documentation. You don't even need special formatting in code comments, because tools like Lazarus IDE can read plain text comments and show them as documentation. Please try it yourself to see what I mean. Displaying your frustration publicly is not going to change anybody's mind [as I found out many times :)], and will definitely not give the developers magically extra time to start documenting code. If the code you are complaining about is commercial software, complain to them. If the code is from an open source project, then you and the community can start the documentation. Regards, - Graeme - ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?
On 12 July 2013 09:09, Graeme Geldenhuys gra...@geldenhuys.co.uk wrote: On 2013-07-12 07:07, vfclists . wrote: Coding time is the best time for documentation because that is when the intent of the code is clear and fresh in the developers mind, and incurs minimal additional cost. And you just said it yourself. If the developer of the code doesn't even have the time to add code comments in his code, why do you think having an Comment property would make it any better? It will not - the developer would still not have any time. You don't need seperate tools to create documentation - code comments can serve as documentation. You don't even need special formatting in code comments, because tools like Lazarus IDE can read plain text comments and show them as documentation. Please try it yourself to see what I mean. Anyway I am not talking about documentation as such, just a property that an object can be queried about on its role, something no different from the Hint property of components, for the developer rather than the end user. Regards, - Graeme - ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal -- Frank Church === http://devblog.brahmancreations.com ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Re: [fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?
On 2013-07-12 10:48, vfclists . wrote: Anyway I am not talking about documentation as such, just a property that an object can be queried about on its role, ie: class documentation :) Regards, G. ___ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
