Gauging your interest for small external doc contribution #50
Comments
Very much so! We've tried to produce good documentation and a small book to help people of all levels to use Miou. Unfortunately, my English isn't perfect, there's a lot of writing involved (which can take a week or 2) and, inevitably, there are typos, a bit of French here and there and not necessarily good reflexivity in all cases in relation to the readers. I'd be really pleased to have feedback on all this and to improve these crucial aspects.
Please, go ahead! I'm not very fussy about ocamlformat and it would indeed be nicer if there were no warnings in the documentation. |
|
Même bateau 🥖 - I'll try to have something going during the cycles I dedicate to Miou. Thanks! |
|
Thanks a lot for attending the PRs! I am somewhere through the reading, and have been enjoying that quite a bit, thank you for this learning material. Before closing this issue, I had perhaps another suggestion, I can detail if you are interested but in a nutshell, I wanted to explore using mdx a bit through the book, and have the examples spinets be automatically inserted from annotated fragments located in actual ml files that would be part of the test build. Pros: the examples in the doc stays up to date, you have the guarantee they type check with the current version of the lib, and you'll be reminded to update them upon changes. Users can use their normal editor goodies when browsing it (personally I like to hover over values with Merlin to see their types). Cons: this adds a test dependency to the mdx tool, and extra build steps when you update the doc. Please let me know if interested and I can offer to have a look, while I'll dig deeper into the reading of the part of the doc. Thanks! |
I'm not a huge fan of mdx and I can be pretty picky about adding dependencies to build documentation. I'm not against, however, adding dependencies for development (as was done for ocamlformat, for example). |
|
It sounds like for now it'll be easier for me to build and explore the book examples on the side. I also noticed some tutorials written as mld files - I don't think I've seen this particular type of use before. That plus your mdx and build dep feedback will give me some things to think about. Thanks! 👍
I think this about wraps it up, and I'm preparing to close this issue. Thank you for your time, and talk soon! |
CHANGES: - Don't try to abusively fill the pipe to interrupt a domain Interrupting a domain involves writing to a pipe to interrupt the `select(2)` if it is running. The pipe has a limited memory, depending on the system, and if you ask to interrupt a domain too much, you end up blocking the `write`. This patch prevents writing to the pipe if it has not yet been read. (@dinosaure, robur-coop/miou#46) - Expose the Sequence module (@dinosaure, robur-coop/miou#47) - Be able to add a hook (effect free) into the scheduler It is possible to add a hook to the scheduler. If the user wants to execute a function to a domain each time the domain is busy with a task, they can do so. However, the effects are not managed in the passed function. (@dinosaure, robur-coop/miou#48) - Add `Miou.Lazy`, a domain-safe `Lazy` module like `Stdlib.Lazy` (@dinosaure, initially implemented by @polytypic, robur-coop/miou#49) - Raise an exception if the user uses syscalls (from `Miou_unix`) and `Miou.run` instead of `Miou_unix.run` If a user uses a suspend function offered by `Miou_unix` but does not use `Miou_unix.run`, the programme may block indefinitely. This patch prevents such an error by raising an exception if we want to add a suspension point and we haven't specified how to handle it (if we use `Miou.run` instead of `Miou_unix.run`). (@dinosaure, reported by @kit-ty-kate, robur-coop/miou#51) - Rename `Miou.set_signal` to `Miou.sys_signal` (@dinosaure, robur-coop/miou#50) - Improve `Miou_unix.{read,write}` (@kit-ty-kate, @dinosaure, robur-coop/miou#52, 2f552a6, robur-coop/miou#54) - Fix an issue related to the dom0 and pending tasks locked by mutexes Tasks may have been transmitted to dom0 while it was executing a task and before the `select(2)`. This patch resynchronises the pending tasks in dom0's TODO-list before making the `select(2)`: specifically to find out whether the `select(2)` can block indefinitely or not. This patch also cleans up the old states of the tables used by `Miou_unix` if it is used on an ongoing basis (as in the case of tests). (@dinosaure, robur-coop/miou#53) - Add `Miou.Domain.available` (@dinosaure, robur-coop/miou#53) - Fix a race condition (observed with TSan) when we wait the cancellation of a children This patch changes Miou's behaviour a little when waiting for a task to be cancelled and prevents invalid access to a value that does not belong to the current domain (and which can be modified by another domain). Thanks @OlivierNicole and @fabbing for their advice on using TSan. (@dinosaure, robur-coop/miou#56) - Update the layout of Miou to avoid conflicts with other packages (like `backoff`) (@dinosaure, reported by @patricoferris, robur-coop/miou#57) - OCaml 5.3 support (@kit-ty-kate, github#22) - Rename `Miou.call_cc` to `Miou.async` (@dinosaure, @kit-ty-kate, @Armael, github#23)
Hello! As I am discovering Miou and reading more, I can propose to submit small corrections to the doc for things like typos, and ask questions about things that give me pause. Would you be interested? (taking the perspective of someone discovering the text for the first time).
In particular I tried compiling the doc and formatting the repo:
dune build \@doc.I can propose to prepare chore PRs to:
Please let me know if you are interested. For me this would fall within the time I allocate to learning Miou anyways, so I see it as valuable for me in the long term, while potentially making very small steps to making it easier to onboard future contributor changes.
Thanks!
The text was updated successfully, but these errors were encountered: