The Sway Book does not contain any examples regarding std usage

[Braqzen]

Summary

Taking a look at the link to the Sway Book for the standard library there is no usage for any type and instead it points the reader directly at the master branch / latest release tag.

That is absolutely not what documentation should be doing.
It's okay to reference the library as an addition for the reader to familiarize themselves with the workings under the hood however we should not be telling the user to "just read the source code".

Every type in the standard library must have its own section which shows simple usage for various usages e.g. initialization, calling some method on the type etc.

This will reduce the questions and confusion from users because they have no reference for the correct usage of the library.
This happens too often and should be prioritized.

[adlerjohn]

So the original idea here was to rely on auto-generated docs with #161, similar to how Rust docs are generated. That would avoid drift between the implementation and the documentation.

As an example, see the docs for Rust's vec (https://doc.rust-lang.org/std/vec/struct.Vec.html) auto-generated from https://doc.rust-lang.org/src/alloc/vec/mod.rs.html.

However, now that I think about this, any example code would require being able to compile and test things from docstrings, which would be a big lift. Putting things info example files included in The Book would provided us with testable code with no further work.

I would therefore be in favor of making a new section in The Book for stdlib types. The content of the section should include only examples of using the types and not documentation on individual methods to avoid duplication. Readers should be pointed to the respective source files to get documentation for methods.

[mohammadfawaz]

Standard library docs generated using forc doc will go live soon. Really important features are finding themselves into the book/reference as needed (such as Result, Option, Vec, etc.). So I'm closing this issue for now.

We will, of course, point to the std lib docs (instead of std lib itself) from the book/reference when they're ready