Closed Bilka2 closed 3 years ago
That's a good idea. Aside from usage examples for specific functions, actual working examples using various parts of flib, with a comparison to the same functionality without flib, would allow people to decide how they will use it. We could stick these in an examples
subfolder.
Ideally examples for specific functions would be generated from the header. Whoever writes a function could do all documentation work in one place.
Edit:
If I remember correctly from yesterday it was something like this:
--@usage local copy_prototype = __flib__.utilities.utilities.copy_prototype
Is general usage, how to require a module or function also necessary?
Concise usage examples can (and should) be included in the documentation, but I think Bilka was suggesting more elaborate examples with real working code?
Edit: Yes, we should generally include a require example right after the ---@module
definition, so it'll appear at the top of the documentation page.
This is what I imagine Bilka had in mind. Fully integrated examples that modders can download and mess with themselves.
They probably shouldn't be quite as long and complicated as that one that I linked, but that's the general idea.
Yep, you got it Raiguard.
Looking at the example, it seems that your library doesn't do valid checking for events it dispatches (you do "entity.valid" checks). If that is the case, it should definitely be documented.
It actually does. If any user data gets invalidated by one of the handler functions, it immediately ceases dispatch.
Some example scripts would be wonderful, especially for the GUI part. I've been trying to replicate the GUI from Rate Calculator because it looks great and it uses flib of course. But I'm having a hard time getting something similar in my mod. Granted I also have no experience with writing GUI's with only the base mod. All the needed functions are documented well, but it is not clear how they should be used together. Documentation of the base mod also suffers from this. Some basic "Getting Started" would be greatly appreciated.
I have not had an opportunity to work on this project as much as I would have liked recently, so the full-fledged examples aren't in yet. However, I did write a test GUI when I was developing the GUI module.
I hope it helps!
That test demo helped a lot! Together with that and more reading of the Factorio and flib docs I understand the GUI part much better. I might spend some time writing examples and create a pull-request if you want.
I added example scripts for event
, gui
, migration
, and translation
a while ago. I don't believe the other modules would benefit from full-fledged examples, but if I have a spare moment I'll write some for them.
Example scripts allow to quickly see how the library can be used, and what the difference is between the API and the library (advantages/disadvantages).