Clarify the drawbacks of unsafe functions

[Kleidukos]

Hi, I'm opening this issue regarding the documentation of the following functions:

---

Nowhere in the module documentation or in those functions it is said clearly the fact that:

• Given an empty vector, head will raise a runtime error;
• unsafe functions do not lead to RTS exceptions (like they may do in other container-like APIs), but will segfault the program. Beginners and more generally people who did not experience this behaviour first-hand are in no way warned of the implications of using unsafe functions (who are then closer than Rust’s unsafe than the commonly accepted definition of safety in the Haskell ecosystem).

I personally think it is dangerous to leave such gaps in the documentation and wanted to discuss this with the maintainers before opening a PR to rectify this.

cc @cartazio

[cartazio]

Good question. Can we back burner it for now though? I’m a bit up to my gills in stuff to juggle. This is a definitely needs some thought and work point. I think also we can flip it around into what should a good maintained doc or cheat sheet reference be? Also pedantically speaking length zero vectors are fine. And it is useful to get an exception from that. As for The unsafe foo operations, their safety depends on the underlying vector type class instance. But you’re essentially right.

…

On Fri, May 8, 2020 at 2:59 PM Hécate ***@***.***> wrote: Hi, I'm opening this issue regarding the documentation of the following functions: [image: Screenshot from 2020-05-08 20-50-20] <https://user-images.githubusercontent.com/15848443/81438748-8bbb6b80-916d-11ea-8ed1-5ab4ec6f2645.png> ------------------------------ Nowhere in the module documentation or in those functions it is said clearly the fact that: - Given an empty vector, head will raise a runtime error; - unsafe functions do not lead to RTS exceptions (like they may do in other container-like APIs), but will *segfault* the program. Beginners and more generally people who did not experience this behaviour first-hand are in no way warned of the implications of using unsafe functions (who are then closer than Rust’s unsafe than the commonly accepted definition of safety in the Haskell ecosystem). I personally think it is dangerous to leave such gaps in the documentation and wanted to discuss this with the maintainers before opening a PR to rectify this. cc @cartazio <https://github.com/cartazio> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#305>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAABBQRNEYKOJXHPEUU5HFDRQRJBRANCNFSM4M4ML4UQ> .

[Kleidukos]

Can we back burner it for now though?

Yes, no problems

I think also we can flip it around into what should a good maintained doc
or cheat sheet reference be?

Will add that to the list of ideas, yes

[Shimuuar]

I think it's quite clear. Current documentation doesn't describe functions' behavior well and it would be nice to make it more informative (PRs are welcome)!

RE unsafe variants. I think all unsafe variants of functions for all vector implementations will happily read/write outside of underlying buffer and cause segfaults (if you're lucky). However it's quite common when things marked as unsafe are really unsafe and your're running with chainsaw that happily buzz in your hands.

All in all I think when documentation miss some aspect of function behavior and someone is willing to improve it there's no reason to not doing it.

[Kleidukos]

@Shimuuar yes, clearly the unsafe prefix is well-deserved for those functions ;)