[Examples] Modernize examples and document

[akhenry]

The examples should be as self-explanatory as possible. They are distinct from step-by-step tutorials in that they provide simple example code for common use cases, and as such should not require detailed explanation.

They do I think need a primer in each directory describing the purpose of the example. Wherever the code would benefit from inline comments to improve clarity this should also be added.

[ghost]

I can take this on as part of my learning process. Let me know if that's okay with you.

[VWoeltjen]

It would definitely be helpful, but we're also in the midst of some API changes (#999 et al) which would render some of that work obsolete in a future release. A different help wanted issue might have more long-term value.

That said, if your motivation is to learn, that would be a good way to do so, and it would still be a great help for us (both to improve our documentation in the short-term, and to have a better starting point when transitioning the examples to the new API.)

So yes, definitely okay with us (and very much appreciated!), just with the caveats above.

[akhenry]

@BogdanAlexandru If you do decide to take this on, there's a related issue to remove and reorganize some of the examples - #841. I'd suggest either taking that issue as well, or skipping the examples that are going to be removed.

And, thanks!

[VWoeltjen]

For context, we plan to have the new API at release candidate status by end of September. (I realize "future release" above was rather vague and may have sounded farther-off.)

[wangsrc]

why

[ghost]

Thanks for the replies!

End of September is definitely soon enough; since this is my first contact I'm not sure how long it'd take until I'm comfortable enough to document everything, and I'm also not sure how long the review process will be until the result is up to par. So overall I feel the primers won't live long enough to be very useful.

Yeah, it's probably wiser to skip this one and learn without the overhead of the writing & PR.

[larkin]

Have updated title, going to use this to track multiple topics related to examples. removing help-wanted.