Recent

Author Topic: A suggestion for a new Lazarus feature  (Read 1093 times)

Ildus03

  • New member
  • *
  • Posts: 7
A suggestion for a new Lazarus feature
« on: July 02, 2019, 07:56:39 pm »
Lazarus already has a package Manager, so I have a suggestion. Add comments to each function and procedures of all packages (or even create an entire article), that is, each user can click on a function, procedure, or class (for example, Alt+Space), and then a window will appear explaining the function... . explanation can be edited, or add a new explanation and add a rating, also who has more rating, the explanation will be shown first (automatically).
(Yandex.Translator)

Handoko

  • Hero Member
  • *****
  • Posts: 3221
  • My goal: build my own game engine using Lazarus
Re: A suggestion for a new Lazarus feature
« Reply #1 on: July 02, 2019, 08:47:31 pm »
That is a great suggestion. But unfortunately, I think it is not likely to happens.

Each package is developed and maintained by their own team. It's all depend on them to provide wiki pages and documentation. Not sure, but I believe many of them is developed and maintained by a single programmer only. Lazarus and the packages are not commercial, they depend on volunteers. Man powers usually is the issue for non-commercial projects.

Luckily, on Lazarus's Source Editor you can Ctrl+Click the identifier to jump the the code for the item so you can learn more about it. Also on Object Inspector, if you hover your mouse on the property for some seconds, a tooltip will show up. You may need to enable Show Hint and Show Information Box on your Object Inspector.

marcov

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 7573
Re: A suggestion for a new Lazarus feature
« Reply #2 on: July 02, 2019, 09:22:28 pm »
(well, he seems to describe doceditor, except for the comment bit)

minesadorada

  • Hero Member
  • *****
  • Posts: 588
  • Retired
Re: A suggestion for a new Lazarus feature
« Reply #3 on: July 03, 2019, 09:14:25 am »
As a component writer, this is a really easy thing to do that will help the user:
Above each published property declaration, write a comment line that will help assist any user to understand it.When properties are displayed in the Object Inspector, if the user clicks on a property, your comment/information will appear at the bottom pf the O.I. window.
i.e.
Code: Pascal  [Select]
  1.   published
  2.     { Published declarations }
  3.     // This is automatically determined when the component loads
  4.     property PlayCommand:String read fPlayCommand write fPlayCommand;  
Most of my components also have an "About" property that displays a summary of the component's purpose etc.
If you publish to Online Package Manager or not, it is very helpful to write as good a description as you can in the package description fields.  I cannot understand how a programmer can spend hours/days writing a component and publish it with little or no description (and sometimes no license info).
..my 2euro
GPL Apps: Health MonitorRetro Ski Run
OnlinePackageManager Components: LazAutoUpdate, LongTimer, PoweredBy, ScrollText, PlaySound, CryptINI

Thaddy

  • Hero Member
  • *****
  • Posts: 9273
Re: A suggestion for a new Lazarus feature
« Reply #4 on: July 03, 2019, 10:05:17 am »
As far as I am concerned, an about should be written in your spare time and not within a company's budget. Same for Easter eggs and the likes. <grumpy again  ::)   >:D>
Non-features....
Note a copyright statement is something different and essential.
« Last Edit: July 03, 2019, 10:07:18 am by Thaddy »
also related to equus asinus.

marcov

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 7573
Re: A suggestion for a new Lazarus feature
« Reply #5 on: July 03, 2019, 10:18:21 am »
Personally I hate in-source documentation. I don't mind some minimal comment, but it has the tendency to expand and become unreadable.
« Last Edit: July 03, 2019, 10:21:43 am by marcov »

Thaddy

  • Hero Member
  • *****
  • Posts: 9273
Re: A suggestion for a new Lazarus feature
« Reply #6 on: July 03, 2019, 10:26:19 am »
Personally I hate in-source documentation. I don't mind some minimal comment, but it has the tendency to expand and become unreadable.
I agree with you, but in a professional environment there is often no planning nor budget to document properly.
In that case I have always insisted that at least the code should be properly documented.
Nobody except Michael  :D :D :D :P ::) :-[ likes to document properly... including you and me....

And thanks to Michael we have excellent documentation!!!!

Dare I even say, best in class....
« Last Edit: July 03, 2019, 10:29:21 am by Thaddy »
also related to equus asinus.

kupferstecher

  • Sr. Member
  • ****
  • Posts: 324
Re: A suggestion for a new Lazarus feature
« Reply #7 on: July 03, 2019, 11:10:56 am »
Personally I hate in-source documentation. I don't mind some minimal comment, but it has the tendency to expand and become unreadable.
Its the easiest and fastest way of documentation (in my opinion). Of course a real documentation would be better, but as well could be additional.
What I try to do is for each public function one or two lines description in the top of the function (implementation part) and for the important puplic properties a short comment behind in the same line for what it is good for. Also a short comment at the top of the unit, what the unit is good for. Its a "for programmers" documentation, not so much for users of packages etc.
The function comments in the implementation part, to keep the "interface" clean and brief for a better overview.

A lot of third party open source packages come without any documentation and often only the examples make it usable for me. A basic in-source documentation would be really helpful there.

Of course a problem is changing the code but not changing the description. But then often it still is better than no comment at all.

marcov

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 7573
Re: A suggestion for a new Lazarus feature
« Reply #8 on: July 03, 2019, 11:25:21 am »
Personally I hate in-source documentation. I don't mind some minimal comment, but it has the tendency to expand and become unreadable.
Its the easiest and fastest way of documentation (in my opinion).

The least infrastucture needed, probably. But  it says nothing about actual ease or fast, since that depends on infrastructure. (and probably in the end out of source is better for that, since it can be made equal, but with better/easier source navigation)

Quote
Of course a real documentation would be better, but as well could be additional.
What I try to do is for each public function one or two lines description in the top of the function (implementation part) and for the important puplic properties a short comment behind in the same line for what it is good for. Also a short comment at the top of the unit, what the unit is good for. Its a "for programmers" documentation, not so much for users of packages etc.
The function comments in the implementation part, to keep the "interface" clean and brief for a better overview.

For any FPC/lazarus stuff, I would directly go the doc interface and invest times in improving that. Investing time in a haphazard in-source solution is double work.
 
Nobody cares if people add some minor documentation to their source, but the OP is about adding infrastructure for such hacks.
« Last Edit: July 03, 2019, 11:51:13 am by marcov »

Martin_fr

  • Administrator
  • Hero Member
  • *
  • Posts: 5756
    • wiki
Re: A suggestion for a new Lazarus feature
« Reply #9 on: July 03, 2019, 01:33:26 pm »
As a component writer, this is a really easy thing to do that will help the user:
Above each published property declaration, write a comment line that will help assist any user to understand it.When properties are displayed in the Object Inspector, if the user clicks on a property, your comment/information will appear at the bottom pf the O.I. window.

In the Lazarus IDE, go to the "View" menu, and open "FpDoc Editor".
Position the text cursor in the editor on any declaration, and you can add/edit docs.

PascalDragon

  • Hero Member
  • *****
  • Posts: 700
  • Compiler Developer
Re: A suggestion for a new Lazarus feature
« Reply #10 on: July 03, 2019, 01:37:31 pm »
(well, he seems to describe doceditor, except for the comment bit)
One should probably also link the Wiki entry for that. ;)

Ildus03

  • New member
  • *
  • Posts: 7
Re: A suggestion for a new Lazarus feature
« Reply #11 on: July 03, 2019, 01:38:13 pm »
I would also like to say, probably, about the most useful improvement in this, is the search among all the comments of all the packages, that is, I, for example, want to turn the picture .JPEG, which is then inserted in the Timade, but I do not know how, I can always start to search the Internet or ask a question on some forum, but you can make it easier, just enter in the window of the Manager of functions and procedures (package Manager) the word "rotate image" and will be a whole selection of comments that have such words, so I will find the package that I need. (This is just an idea)
(Yandex.Translate)

marcov

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 7573
Re: A suggestion for a new Lazarus feature
« Reply #12 on: July 03, 2019, 11:48:57 pm »
I would also like to say, probably, about the most useful improvement in this, is the search among all the comments of all the packages, that is, I, for example, want to turn the picture .JPEG, which is then inserted in the Timade, but I do not know how, I can always start to search the Internet or ask a question on some forum, but you can make it easier, just enter in the window of the Manager of functions and procedures (package Manager) the word "rotate image" and will be a whole selection of comments that have such words, so I will find the package that I need. (This is just an idea)
(Yandex.Translate)

How about this one: https://stackoverflow.com/questions/848025/rotating-bitmaps-in-code

Or do you prefer assembler?

https://stackoverflow.com/questions/47478010/sse2-8x8-byte-matrix-transpose-code-twice-as-slow-on-haswell-then-on-ivy-bridge

and
http://www.stack.nl/~marcov/rot8x8.txt

P.s. the CHM help already has indexes for search. It just needs to be implemented in lhelp I guess.
« Last Edit: July 03, 2019, 11:53:58 pm by marcov »

dsiders

  • Full Member
  • ***
  • Posts: 232
Re: A suggestion for a new Lazarus feature
« Reply #13 on: July 04, 2019, 01:12:36 am »
For any FPC/lazarus stuff, I would directly go the doc interface and invest times in improving that. Investing time in a haphazard in-source solution is double work.
 
Nobody cares if people add some minor documentation to their source, but the OP is about adding infrastructure for such hacks.

Well, that's sounds reasonable enough until you confront reality.

Contributing to RTL and FCL for FPC is simple enough. It'll be applied, and documentation files will be built. The release cycle is just longer.

The problem is Lazarus and LCL. No one who has commit access to SVN is interested in documentation for Lazarus or LCL. If you don't believe me, just check the bugtracker for unapplied/unassigned documentation submissions. Please take note of their ages. Also look for the updates added in the last year. How many times has LCL documentation been "Built" in that time period?

The problem isn't tools or infrastructure for help. The tools work. The infrastructure is in place. The problem basically appears to be that nobody cares about documentation. Et Viola.
Lazarus 2.0.4 / FPC 3.0.4 / Windows 8.1 64-bit

minesadorada

  • Hero Member
  • *****
  • Posts: 588
  • Retired
Re: A suggestion for a new Lazarus feature
« Reply #14 on: July 04, 2019, 08:52:32 am »
In the Lazarus IDE, go to the "View" menu, and open "FpDoc Editor".
Position the text cursor in the editor on any declaration, and you can add/edit docs.

That's a handy tip Martin.  As I suspected the documentation for use and deployment of FPDoc is pretty thin in the Wiki, but I'll try to investigate and improve the Wiki if I have time.
- Thanks!
GPL Apps: Health MonitorRetro Ski Run
OnlinePackageManager Components: LazAutoUpdate, LongTimer, PoweredBy, ScrollText, PlaySound, CryptINI