Add examples to rustdoc

[itowlson]

Fixes #34. Further to spinframework/spin#3007.

@kate-goldenring I'm opening this as draft with just a few KV examples done to get feedback on is this the kind of thing you are asking for, or am I missing the mark? If you're happy with the style and approach then I'll press on, otherwise I'd be delighted to iterate with your guidance!

(For folks who want to see how it looks rendered, cargo doc --lib --open.)

As mentioned in spinframework/spin#3007, there may be challenges with adding examples to methods defined in WIT, and it would be useful to understand how folks want to proceed there... Note also that Rust appends the WIT docs at the end of the handwritten docs (after the examples) and I have not yet found an incantation to turn this off!

(ETA: Lann asked for http::send examples - did some of those too.)

(ETA: per Kate's feedback, continuing to build out, a bit ad hoc but eh.)

[itowlson]

Triggering an error to test CI successfully failed, undid the error

[kate-goldenring]

This is great @itowlson -- definitely what i was looking for.

There may be challenges with adding examples to methods defined in WIT, and it would be useful to understand how folks want to proceed there

Is the current state of this just that the wit docs are appended? I am seeing docs around spin_sdk::key_value::Store

[itowlson]

@kate-goldenring I think there are two things in your message, although they are related.

First off, yes, for re-exports like Store, the WIT docs are appended to the rustdoc. If you look at the bottom of the Store docs you see the original WIT docs sneaking in:

It's minor in this case, but for larger WIT docs could be intrusive. And I can't find a way to turn it off for re-exports.

Second, though, and more directly to the bit you quote, we can't add rustdoc to things we don't re-export in the crate (and hence the only doc is the generated WIT doc). In particular, that means we can't override WIT method docs at all. E.g.:

In Rust docs this should say Ok(None), and it might be nice to include an example as we do for get_json. But this is a generated method, directly surfaced into the API without explicitly appearing in the SDK code, so there's nowhere to attach rustdoc to it (even if we were okay with having the WIT doc appended).

Does that clarify the difficulty? I feel I might be trying to over-explain and thereby making it even more confusing!

[kate-goldenring]

@itowlson that does clarify the issue well for me. I think your strategy of highly documenting the struct (Store) and leaving the methods relatively undocumented may be the best path forward

[itowlson]

Calling this ready for review even though it's a bit patchy - I need to look at some other stuff and I reckon we may as well merge what we have, and bring more of it up to speed over time.

[kate-goldenring]

This looks great @itowlson! Thank you for all of this work. Maybe we can create issues to track adding docs/examples to some of the other parts of the SDK (namely mqtt, pg3, mysql, variables). Those could be great ones for community members to pick up and see this PR as an example