Potential improvements to documentation

[mooreryan]

I wanted to start a discussion on potential ways to improve the re documentation.

Two ways come to mind:

• Add examples for most functions in the API docs
• Write a tutorial or overview style documents separate from the API docs
  • Either included in the package documentation, e.g., the brr package has some overview/tutorial style pages in addition to the API docs:
    • https://erratique.ch/software/brr/doc/web_page_howto.html
    • https://erratique.ch/software/brr/doc/ffi_cookbook.html
  • Or separated, as in external blogs
    • E.g., I have written a introduction to the re2 package on my blog, and was considering writing a similar one for ocaml-re.

Examples in the API docs would be a nice addition I think, but I could also see an argument for keeping the API docs a bit terse and not including examples for every function. Additionally adding examples for every function could be a pretty large project. Would it be acceptable to add examples to a couple functions here, and a couple there, until eventually most of them get examples. Or would it be better to only add them in one shot?

Tutorial or introduction style pieces would also be nice, but including them in the package docs could be potentially tricky as different authors may have different ideas on what such pieces should include or cover. Keeping those in separate location (eg blog posts) would avoid that problem, but they potentially wouldn't be found by beginners to the library. (However, it is interesting to note that the first google search result for ocaml regular expression library tutorial as of today was my blog post about Jane Street's re2 library....)

I have some time to dedicate to this and will, at the least, adapt my re2 blog to give an intro to the re library. In-package doc improvements could be helpful as well, but I don't want to start on anything like that without hearing from the package maintainers.

---

Here are some links for additional context.

Here is a excerpt from a discuss post by jbeckford:

Almost all of the documentation for OCaml libraries is API-level documentation. For example, the regular expression re 10 library has very good API-level documentation, and it has some examples. But the quantity and comprehensiveness of the examples aren’t sufficient to help a newcomer. So I’ll be teaching a tribal-knowledge trick: looking at a library’s unit tests in its source code. If only test code was automatically included in the documentation!

Here are a few links to issues or pull requests regarding documentation and examples.

• Clearer documentation for Re.eol #119
• Please add a warning that Re.Str is not thread safe #194
• Re.Posix does not implement character class expressions? #213
• Add examples for Re.split function #216