We will have to agree to disagree. I find the python docs far more usable than the OCaml documentation. I don’t understand why search wouldn’t work for you, it works fine for me on Python and Ruby pages, and I use those docs all the time. I find the OCaml docs very hard to use by contrast — they’re both badly formatted and broken up in odd ways that make reading them harder.
(I like the Ruby docs even more, for what it’s worth.)
I can understand that reading an .mli file can give an understanding of what type of input i should provide to a function and what i get as an output but it hard for me to know the purpose of a function, when to use it and how to use it.
use batteries, it has an excellent documentation.
When someone publishes a library, that someone should write some working tests that can be used as usage examples.
I prefer runnable code to outdated textual documentation.
I did this for my dolog library:
Excellent example. I really like this approach over documentation because it is much faster to get my code working than reading the doc and trying to come up with code.
It should not be an either-or problem. Lwt’s docs for instance incorporates copy-paste-and-run standalone examples along with the exact command to run it. IMO both runnable examples and documentation are equally important if we want our libraries to be used by others.
Indeed, and tests and samples are not substitutes for documentation, and I’m completely against attempts to substitute them for documentation. Good documentation has plentiful examples, though.
There is a third middle road though: make the code samples in the docs run inside your test suite. I’ve built this feature twice: once for Python and once for Clojure:
I’ve even made sure that the line numbers of these test runs line up with the markdown. It’s pretty sweet.
That sounds like a neat idea. Have you considered doing this for OCaml? Would be glad to help.
I’m very much in favor of example code being automatically tested.
I don’t have the time and I’ve stopped looking at OCaml at all for the time being. But look at the Python or Clojure code. It’s really a tiny hack. Should be able to do it in an hour if you know OCaml and parsing.
The algorithm is:
Load the lines of the doc into an array
Replace all text lines with blank space, keeping only the code
Use those blank lines to insert whatever boilerplate you need for the tests
Bonus points: if the examples have comments to show results, convert them to asserts.
There is a third middle road though: make the code samples in the docs run inside your test suite.
I am in the process of releasing https://github.com/samoht/mdx which is doing something similar. Documentation is still lacking a bit and I want to change/improve a few more things before the release, but feedback is already welcome.
I don’t think this issue has been discussed in this thread so I will state it here. Coming from C/C++ background with my past work experiences in system programming and tools. What nearly killed my interest in OCaml was the unconventional integers and lack of built-in unsigned integers.
I know there are libraries supporting various sizes of unsigned integers, but none is as convenient as built-in types.
Do you make it so that if you get compiler errors or runtime errors they match the line numbers in the markdown doc? I think this s key!
Does such a thing as conventional integer exist? And there are 32 and 64 bit integers, unsigned types are incoming btw.
Yes it matches line and column numbers. It also automatically update toplevel fragments with the corrected output.