Mention fiber/status + last-value in main text

[sogaiu]

Following on from the point made toward the end of this comment, this PR is an attempt to appropriately mention fiber/status and fiber/last-value in the main text.

So far the text of the Fiber overview page and the Error handling page have modification suggestions.

I also made changes to some related code examples.

Another related change is the addition of a note about synonyms for the term "trap" with respect to signals. I did not find this term among any docstring. I only recognized it in the website docs, specifically, on the Fiber overview page. Among the docstrings, the terms that I identified for the concept were: "block", "capture", and "mask".

---

If I've missed relevant mentions of fiber/status and/or fiber/last-value, please point them out. I know they appear in the following places:

• Fiber overview page - fiber/status mentioned in example code
• Error handling page for fibers - fiber/status mentioned in example code
• Multithreading page - both mentioned in passing

However, these are not really direct introductions to either.

[amano-kenji]

I think https://janet-lang.org/docs/fibers/error_handling.html should mention fiber/last-value is the error value.

It adds a bit of redundancy to https://janet-lang.org/docs/fibers/index.html, but it will lead to less confusion.

People learn from repetition. Repeat the same thing again and again 100 times, and people will finally get it.

I am your llama who spits at you 100 times so that you cannot ignore something.

[sogaiu]

Thanks for the suggestion, I will consider it.

---

If you look over the histories of various Janet repositories, I think you'll see that I (and others) have been motivated over the years to improve various things including documentation.

This has been happening without your llama comments. Those are unnecessary, distracting, and frankly likely to lead to annoyance. If you persist in that activity, I think it may lead to a decrease in motivation and/or redirection of time, energy, and effort in counterproductive or disspitative things (e.g. I am not spending time improving Janet documentation here because I'm writing this part of the response). That seems contrary to improving Janet so I suggest you stop making such comments.

[amano-kenji]

Right. You don't need a llama. I'm going to stop being a llama.

[sogaiu]

I've made some more changes and pushed them to this PR, both to the Fiber overview page and the Error Handling page.

I'm likely to be mulling over the content more, but am not adverse to hearing about the content in its current state (^^;

[amano-kenji]

I finished reading it. It is excellent.

[sogaiu]

Thanks for taking a look.

---

I've added a note about synonyms for the term "trap" in reference to signals. The ones I've come across so far include:

• "block" - fiber/new's docstring
• "capture" - fiber/new's docstring
• "mask" - with-dyns' docstring

I didn't find "trap" in any docstring [1], but it occurs on the Fibers overview page.

---

[1] To do this kind of search, it's convenient to search on this page. Though when the docs are not for the latest version of Janet, the search is perhaps not quite complete.

[bakpakin]

Just for some explanation of why it's missing, fibers didn't use to store their last values at all and in many cases it is redundant. However it was needed for a couple of things like iterating over fibers and the certain things in the ev module.

[sogaiu]

Thanks for the background!

---

For future readers, it looks like this might be one of the relevant commits. (The commit was located by looking for where Janet last_value; /* Last returned value from a fiber */ got added in janet.h.)