search

janestreet / base

Standard library for OCaml
MIT License
860 stars 125 forks source link

docs(list.mli): add example for map2 #86

Closed rbjorklin closed 3 years ago

rbjorklin commented 4 years ago

OCaml overall lacks softer documentation as called out in the OCaml Documentation Open Thread. I'd be happy to add some examples as I go along and figure things out. My commit message follows the Conventional Commits style, I hope that is ok.

Signed-off-by: Robin Björklin robin.bjorklin@gmail.com

bcc32 commented 4 years ago

Thanks for the contribution! I'm a little bit confused by your example, though. It seems a bit of an odd choice to return the empty list in the case where the two lists have unequal lengths.

For what it's worth, I think map2's documentation is pretty clear as it stands, but there are definitely some functions whose documentation would be much clearer through adding some examples, e.g., chunks_of, cartesian_product, partition_map.

Adding examples to our documentation is definitely something we're actively working on. In fact, we're developing some ways to make runnable examples possible in mli files, so that the examples are compiled and run as part of automated tests! :smile:

bcc32 commented 3 years ago

I'm closing this PR due to inactivity, but please feel free to reopen if you have a different example you would like to contribute. We will also continue to work on improving our libraries' documentation, including adding examples.