User study issues

[tertsdiepraam]

I did a session with @JonathanBrouwer where he tried Roto while I took notes on the problems and papercuts he encountered. This is the list of notes I took:

• The hello world example creates some confusion between the binary and the library and how they relate.
• Rethink API for standard library features #329
• The error message for print not being enabled should hint add enabling io functions.
• Lists need to be documented.
• The variant name is not intuitive.
• "no method to_string" should include a hint on what to do and be more descriptive. At least until writing methods for Roto types becomes possible.
• Type aliases for registering Roto types is confusing because people will try to use the alias. It's not clear that they shouldn't.
• "expected Verdict" should hint towards looking at the accept/reject keywords.
• Items in docs.rs should refer back to the library! macro because people probably shouldn't be using them directly.
• Anonymous records are still ambiguous with blocks in the parser.

---

• Using // as comment should be caught and hint towards using #.
• If an identifier looks like a keyword from other languages, we should hint that it isn't and guide towards the correct keyword if a parse error occurs. (e.g. for, use, enum)
• Making modules in the Runtime breaks horribly if a type is declared in a module. #316
• The docs point to latest by default instead of stable, which is confusing if you use Roto from crates.io.
• The "call a roto function" block was missing a semicolon.
• The standard library docs should link more to the language reference. For example, Option should link to pattern matching.
• The docs for Option should also explain how to work with options: explain matching and ?.
• The docs for Option say "like any enum"
• "Add functions" in the docs does not explain the use of Arc<str>
• In "Add types" the Val type is explained too late.
• The RegisterableFn trait not being implemented gives really bad errors. We should dive into the diagnostics attributes thing or try to catch some problems in the proc macro already to give more specific errors.
• "Add methods" should be using the self parameter.
• Tests should be sorted before being run.
• The cli method needs more docs and should also state whether it diverges by returning !
• There needs to be an "Add modules" section in the docs.
• Tests should be documented.

[tertsdiepraam]

I'm checking the items I've got fixed on a branch I'll put up soon