Hello,
I have heard that the stdlib is in need of many more examples, and I'm wondering how I can help out.
I have two questions:
Your help is most welcome!
How should I handle testing these examples? Should I use runnableExamples? I've never used it before. Could someone demonstrate?
that's why we need a detailed guideline doc showing latest best practices with code snippets (which I started here https://github.com/nim-lang/Nim/pull/8271)
Should I use runnableExamples?
yes for the most common usage, not meant as replacement for proper unittesting; search in doc for runnableExamples and run nim doc foo/bar.nim : it'll run these (but see caveat here: https://github.com/nim-lang/Nim/issues/7280) and generate bar.html which you can inspect for formatting issues if needed (see also https://github.com/nim-lang/Nim/issues/8477 which is a meta issue listing documentation issues I ran across).
Please report any bug you encounter with runnableExamples (after checking they're not already reported)
What procs really need examples? > I suppose it's the more advanced ones that should be documented?
ideally every symbol should be documented but we need to prioritize; so here's a simple heuristic: look for modules with few runnableExamples that are you're either familiar with or that are more commonly used: nimgrep --ignoreStyle --ext:nim --recursive --oneline runnableExamples
Does each module get a separate pull request, or is it just one pull request for a chunk of work across modules?
I think 1 PR per module is good; keep in mind PR's are queued and each push to a PR uses up resources on travis/appveyor (and takes a loooong time)
Yes, the stdlib is in dire need of more documentation.
For the options module specifically I don't think documentation for specific procedures is what is needed. We need documentation at the top of each module explaining its purpose, along with small and specific examples (that are cook-book like). For example, see the httpclient docs: https://nim-lang.org/docs/httpclient.html, these aren't perfect but they're a good start.
The one thing that you shouldn't do is add a large example in the docs that shows off various features of the module. It's not easy for readers to pick out the information they need that way.
but some of the procs (e.g. isSome) are obvious
That's not true. Imagine a developer who has never used functional programming. They will likely have absolutely no idea how to use the options module.