Recent

Author Topic: How to discover information about packages, classes, etc.  (Read 2218 times)

jouborg

  • New Member
  • *
  • Posts: 11
How to discover information about packages, classes, etc.
« on: December 26, 2020, 04:14:01 am »
Is there a way to discover / browse packages included in fpc/Lazarus and see what functionality they provide?

So far, I've tried:

1. Reference material
     - Online documentation https://www.freepascal.org/docs.html
     - Documentation search https://www.freepascal.org/docsearch/docsearch.var
     - Wiki (search and browse)

2. From within Lazarus
     - Menu: View | Code Browser
     - Menu: Package | *
     - Menu: Help | Help (seems to draw from the online docs, and is similarly missing information about available packages)
 
However, neither technique give any information about the available packages.

Right now the only way for me to discover available packages and what functionality they provide, is to browse the fpc source code directly. For example, I cannot "discover" information about what Generic Collection classes there are and their interfaces without first opening up /usr/local/share/fpcsrc/3.2.0/packages/rtl-generic/src/generics.collections.pas and then reading through the source code or using the Code Explorer.

This is super tedious and I'm sure there must be a better workflow.

What am I missing?
« Last Edit: December 26, 2020, 04:16:43 am by jouborg »

Handoko

  • Hero Member
  • *****
  • Posts: 4327
  • My goal: build my own game engine using Lazarus
Re: How to discover information about packages, classes, etc.
« Reply #1 on: December 26, 2020, 04:46:06 am »
I usually use Google Search Engine and add "Free Pascal" for the search text. For example "Free Pascal Generic Collection". Sometimes I use the documentation from Delphi.

If what I'm looking for is a third party package which is not installed by default, I use Online Package Manager. There I can get a short description about the package and most importantly its official URL, which I will then visit to get the documentation.

I guess you already knew, the documentations of Lazarus and Free Pascal can be improved. There were several discussions about it, unfortunate not much work has been done. Manpower issue.

I think there is no a better workflow. But there are many things we can do to better understand the package. Including examine the source code.
« Last Edit: December 26, 2020, 06:53:53 am by Handoko »

lucamar

  • Hero Member
  • *****
  • Posts: 4219
Re: How to discover information about packages, classes, etc.
« Reply #2 on: December 26, 2020, 05:58:24 am »
This is super tedious and I'm sure there must be a better workflow.

Yes, it's tedious and there's no better workflow: search the docs, search the wikis, search the forum and then the web at large; stop when you find what you're looking for or, if you don't, dive into the sources.

You've just discovered FPC/Lazarus's dirty little secret: there are quite a lot of included packages, extensions, libraries and bindings which are either barely talked about in the wiki (and sometimes here, in the forum) or not documented at all.

But you can help: if you see something you would like to use, use it and learn something worthwhile about it, document it, even if just by adding/modifying a page in the wiki. This is a volunteer project: become one yourself!  :)
« Last Edit: December 26, 2020, 06:01:47 am by lucamar »
Turbo Pascal 3 CP/M - Amstrad PCW 8256 (512 KB !!!) :P
Lazarus/FPC 2.0.8/3.0.4 & 2.0.12/3.2.0 - 32/64 bits on:
(K|L|X)Ubuntu 12..18, Windows XP, 7, 10 and various DOSes.

jouborg

  • New Member
  • *
  • Posts: 11
Re: How to discover information about packages, classes, etc.
« Reply #3 on: December 26, 2020, 05:57:41 pm »
Thanks, Handoko and lucamar.

Thinking out loud:

a) the wiki enables a collaborative, editorial perspective without being constrained by source code / package structure. This has certain advantages over a more scalable autodoc (e.g. using fpdoc) approach.

b) a package browser in Lazarus of local packages (any directory) could really help discovery but a standalone app can also help in those cases where someone doesn't use the IDE.

c) broadening the scope of the online docs (https://www.freepascal.org/docs.html) to include ALL the packages that ship with Free Pascal would also help discovery and learning, especially if the package sources are documented well.

I think all three have merit so I'm keen to do something on all 3 fronts.

For (b), a cursory Google search doesn't turn up anything existing so I could spend some time building that.
For (c), I'd like to see whether I can change the build process for https://www.freepascal.org/docs.html to include the broader set of packages. Where is the infrastructure / configuration / source for building the online docs?

« Last Edit: December 26, 2020, 06:07:56 pm by jouborg »

Handoko

  • Hero Member
  • *****
  • Posts: 4327
  • My goal: build my own game engine using Lazarus
Re: How to discover information about packages, classes, etc.
« Reply #4 on: December 26, 2020, 06:56:16 pm »
I'm not sure but I think you may want to join the bugtracker and try the FPDoc Editor:
https://wiki.freepascal.org/Lazarus_Documentation#Missing_documentation.3F

marcov

  • Administrator
  • Hero Member
  • *
  • Posts: 9516
  • FPC developer.
Re: How to discover information about packages, classes, etc.
« Reply #5 on: December 26, 2020, 09:18:50 pm »
a) the wiki enables a collaborative, editorial perspective without being constrained by source code / package structure. This has certain advantages over a more scalable autodoc (e.g. using fpdoc) approach.

Even in the fairly open WIKI, 90%+ happens by a few regulars.  And even the remaining 10% is rarely documenting of features, but more often pushing of some feature request, own package or making some other point in some discussion.

Moreover, to sync the wiki with the source requires work too, and software would have to be developed, and would be have to adapted/rewritten if the wiki software changes.
fpdoc is fairly free from that, and its parser is also used for other things like pas2js, and more importantly, it is done, and in sync with the rest of the project.
Anyway, wikis from large projects are also limited in write access. Otherwise too much spam, discussion etc happens, or simply low quality documentation is written.

Quote
b) a package browser in Lazarus of local packages (any directory) could really help discovery but a standalone app can also help in those cases where someone doesn't use the IDE.

There is fppkg, but OPM and fppkg are not linked atm afaik.

Quote
c) broadening the scope of the online docs (https://www.freepascal.org/docs.html) to include ALL the packages that ship with Free Pascal would also help discovery and learning, especially if the package sources are documented well.

You can submit patches in mantis/bugtracker  :)

Quote
For (c), I'd like to see whether I can change the build process for https://www.freepascal.org/docs.html to include the broader set of packages. Where is the infrastructure / configuration / source for building the online docs?

Start documenting, and if ok, a new link to the new docs will be added and become visible the next release. Or you can build your own html or CHMs with fpdoc.

lainz

  • Hero Member
  • *****
  • Posts: 3837
Re: How to discover information about packages, classes, etc.
« Reply #6 on: December 27, 2020, 05:39:04 am »
I tried to document bgracontrols, but is a slow process, slower than coding.

I prefer tutorials, demos and real use cases instead. At least in BGRAControls we have a lot of demos, so for your knowing maybe is just enough knowing that these are GUI controls with custom styles (not native style), and that works cross platform.

That kind of information can be shown in online package manager website maybe, it shows already some description.

At least I'm thinking in the OPM third party packages, not the FPC ones.

PascalDragon

  • Hero Member
  • *****
  • Posts: 3310
  • Compiler Developer
Re: How to discover information about packages, classes, etc.
« Reply #7 on: December 27, 2020, 10:10:15 am »
c) broadening the scope of the online docs (https://www.freepascal.org/docs.html) to include ALL the packages that ship with Free Pascal would also help discovery and learning, especially if the package sources are documented well.

We only include units that are fully documented.

You can however find a snapshot of all packages here.

lainz

  • Hero Member
  • *****
  • Posts: 3837
Re: How to discover information about packages, classes, etc.
« Reply #8 on: December 27, 2020, 12:05:29 pm »
c) broadening the scope of the online docs (https://www.freepascal.org/docs.html) to include ALL the packages that ship with Free Pascal would also help discovery and learning, especially if the package sources are documented well.

We only include units that are fully documented.

You can however find a snapshot of all packages here.

I can understand why these are not included, it just displays unit names, at least in the packages I randomly opened.

Andrey Sobol

  • New Member
  • *
  • Posts: 48
Re: How to discover information about packages, classes, etc.
« Reply #9 on: December 27, 2020, 06:23:06 pm »
We only include units that are fully documented.

You can however find a snapshot of all packages here.
I think that it is not right. When you don`t include templates of packages (and don`t generate chm files) so you do more uncomfortable filling of documentation. I thought for example that fcl-image packet template not exist and started to create it insted of writing of documentation.
I think that a packet should be included into documentation if exists only description on 2-5 sentence and template.
Many users start write same code because then don`t understand what yours packages do.
To write descriptions.. this is one day of work for a person who is familiar with the purpose of packages.
I can place a needed packet chm into doc folder and use it. I will see all classes, functions and so on.

Process of filling documentation is difficult now. I Don`t say about using fpdoceditor.
I say about:
- create template (without this you can`t generate test.chm)
- write description (FULL description!)
- open issue on bug tracker (Where? In main level is only FPC).
- Wait for uncertainty that someone will be placed in repo.
- wait
- wait and wait.

I want quickly to create a help for myself and share the result with others.
When it will be convinient then we quickly create a documentation.

The greatest thank to helpers, which include examples of code :)

MvC

  • New Member
  • *
  • Posts: 21
    • Free Pascal Core team member
Re: How to discover information about packages, classes, etc.
« Reply #10 on: December 29, 2020, 11:13:49 am »

If you are looking for information about packages, see:

https://www.freepascal.org/daily/daily.html

This is updated daily from the sources.

marcov

  • Administrator
  • Hero Member
  • *
  • Posts: 9516
  • FPC developer.
Re: How to discover information about packages, classes, etc.
« Reply #11 on: December 31, 2020, 05:20:22 pm »

If you are looking for information about packages, see:

https://www.freepascal.org/daily/daily.html

This is updated daily from the sources.

Where is the project to generate that?

 

TinyPortal © 2005-2018