Move readme examples into `Example` functions

TBD54566975 / web5-go

Apache License 2.0

10 stars 6 forks source link

Move readme examples into `Example` functions #23

Open mistermoe opened 7 months ago

mistermoe commented 7 months ago

Suggested by @alecthomas. Beneficial bc examples are runnable and changes to api surface will cause examples to break which will cause builds to fail.

Tried to use them 2ish weeks ago but they weren't rendering where I wanted them to. I Think I was being too nit picky tho

KendallWeihe commented 6 months ago

How would this fit into the codebase? I'll throw out my non-thoughtful ideas...

[ ] examples/ package with comprehensive examples (dunno what "comprehensive" means?)
[ ] Add instructions in README to inform user to go to examples/ rather than expect them inline in the README
[ ] Ensure the examples are included in the build phase (to ensure breaking changes are fixed)
[ ] ...how to me them "runnable" (from the description, "Beneficial bc examples are runnable")? Or is this even necessary?

KendallWeihe commented 6 months ago

Or, should we have {package}/{something}_examples.go in each package? Like we do tests? ...yeah I think I like that better.

alecthomas commented 6 months ago

In Go, examples are part of the test framework, so they go in *_test.go files, and are tested as part of the normal testing process. They'll also show up directly as runnable examples in the Go docs on pkg.go.dev

Here's a good article on them.