Add a quickstart/cookbook with annotated examples #279
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Rationale:
Get new users of Snafu going as quickly as possible using the library, by showing the common patterns by example.
I believe that once people see the power of Snafu and use it, they are more likely to invest additional time learning more of how it works, which the rest of the documentation excels at. However, at first they just want to get on with whatever project they are working on with minimal upfront effort.
Change:
This PR proposes to add a quickstart / cookbook at the beginning of the Snafu docs with all the key concepts I would have liked to know as a new Snafu user while working on IOx (and that we have partly codified in https://github.com/influxdata/influxdb_iox/blob/main/docs/style_guide.md#errors)
Notes
The other thing that would be very helpful is to have an API doc somehow for for the generated context selectors but I couldn't figure that out.
For example, I can't find any documentation for the
fail
function that is on context selectors in the docs:Since these types are are generated using macros, my IDE also doesn't help tell me what is available. I realize this may be technically challenging, but I wanted to mention it as something I (still) really want to be able to access but haven't been able to find out.