Forum > Documentation (Maintaining -)
How to discover information about packages, classes, etc.
marcov:
--- Quote from: jouborg on December 26, 2020, 05:57:41 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.
--- End quote ---
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.
--- End quote ---
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.
--- End quote ---
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?
--- End quote ---
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:
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:
--- Quote from: jouborg on December 26, 2020, 05:57:41 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.
--- End quote ---
We only include units that are fully documented.
You can however find a snapshot of all packages here.
lainz:
--- Quote from: PascalDragon on December 27, 2020, 10:10:15 am ---
--- Quote from: jouborg on December 26, 2020, 05:57:41 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.
--- End quote ---
We only include units that are fully documented.
You can however find a snapshot of all packages here.
--- End quote ---
I can understand why these are not included, it just displays unit names, at least in the packages I randomly opened.
Andrey Sobol:
--- Quote from: PascalDragon on December 27, 2020, 10:10:15 am ---We only include units that are fully documented.
You can however find a snapshot of all packages here.
--- End quote ---
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 :)
Navigation
[0] Message Index
[#] Next page
[*] Previous page