search

factoriolib / flib

A set of high-quality, commonly-used utilities for creating Factorio mods.
https://mods.factorio.com/mod/flib
MIT License
64 stars 15 forks source link

Suggestion: Add example scripts #4

Closed Bilka2 closed 3 years ago

Bilka2 commented 4 years ago

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).

raiguard commented 4 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.

0ptera commented 4 years ago

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?

raiguard commented 4 years ago

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.

raiguard commented 4 years ago

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.

Bilka2 commented 4 years ago

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.

raiguard commented 4 years ago

It actually does. If any user data gets invalidated by one of the handler functions, it immediately ceases dispatch.

UnseenBook commented 4 years ago

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.

raiguard commented 4 years ago

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!

UnseenBook commented 4 years ago

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.

raiguard commented 3 years ago

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.