Comprehensive examples for documentation

[cjdb]

I find it very difficult to learn how APIs work without clear examples of intended usage, even for very simple things. Would it be too much trouble to add examples to each part of the API so that the intended use is clear, please? Examples for demonstrating and discussing general use (e.g. sus::ptr's demo would go somewhere on the main sus::ptr page) and for each part of the API (e.g. sus::ptr::as_ref examples would be put in the sus::ptr::as_ref page) would be appreciated.

This is potentially a subtask of #321.

[danakj]

Agreeing more docs and examples are needed :) Only a few sections have gotten that higher level of attention so far, like option.