API "entry points" lack reference documentation

[git-staus]

In order to progress with #14, the parts of the API that make non-empty types out of maybe-empty ones need clear documentation.

Since I am unfamiliar with the code I have to rely solely on the existing documentation and therefore can more easily pinpoint where beginners are most likely to struggle. Here is a list of what I can and cannot find out about making non-empty Vecs and iterators from the current documentation. If an expert could confirm / deny or supplement my descriptions it might yield some decent docstrings.

I am purposefully being a bit sloppy here (not reading the implementing code etc.) – the "design for people who are smart but in a hurry" maxim I cannot find a source for. I don't mean to be entitled!

vec1! and Vec1::from_one

These are really obvious from their signatures alone and probably do not need more documentation. However, their use cases seem limited to hard-coded data so I guess beginners like me will keep looking.

Various try_from and try_into methods

These is also obvious API members you might try out before even looking at the documentation. In the documentation they end up in the usual uninformative list of blanket implementations (I only found out they existed from issue comments). Searching for them yields many for various structs and traits. (Unclear where the latter apply; the route of least resistance seems just trying them out and see if it compiles.)

Is this the intended mechanism to create non-empty types from maybe-empty ones or are these only useful for implicit coercions?

Maybe I am running into gaps in my own Rust knowledge instead here, but – for beginners at least – a comprehensive narrative example somewhere is probably more useful than API reference documentation for all these methods, given the aforementioned over-crowding in the docs.

try_into_iter1

Implemented on a trait that (probably?) applies to maybe-empty iterators. I cannot figure out how this one compares to the aforementioned try_from and try_into methods.

Iterator1::try_from_iter

The same applies as for the above. Maybe this is its mirror counterpart? It is implemented on a different struct though.

Vec1::from_head_and_tail and head_and_tail etc.

Methods like these are used in the examples, but sometimes with more items than just a "head" and a "tail". I don't understand these methods at all.

or_non_empty and extend_non_empty

These are referred to as

methods for bridging between non-empty Iterator1 types and maybe-empty Iterator types

but if I am not mistaken these require some fallback value (or is the latter only meant for extending?), which again are only demonstrated with hardcoded values in the example code. They return custom objects that I cannot relate back to the base types with a reasonable about of effort. Perhaps these are not really general "entry points" into mitsein, are they?

try_collect1

This one appears to be the mitsein version of std::iter::try_collect (still unstable). My understanding is that .try_collect::<_>() is just a shortcut for .collect::<Result<_>>(), but I might be wrong. Additionally, try_collect1 does not seem to behave that way either.

collect1

My main go-to method, but I cannot get it to work. The signature is also completely opaque to me. Is it only meant for collecting iterators that are already non-empty types rather than creating non-empty types from maybe-empty ones? Why can non-empty types not just use std::iter::Iterator::collect?

Other methods?

There are probably more that I am unable to find. Simply having a listing with all of them somewhere might already shorten the time beginners will need for experimenting in order to become productive with mitsein.

PS

My "insights" alone did not yield the snippets of PR-level material I hoped, but maybe the above is at least a useful starting points for writing documentation.

[git-staus]

I wanted to add I am still actively using mitsein and getting more comfortable using it. I am contemplating writing it all down afterwards and sending in a PR for this issue.