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.
1 Like
(I like the Ruby docs even more, for what it’s worth.)
Call me biased, but the best documentation I’ve seen is Erlang’s. I have no idea why, and that’s despite the fact that pretty much everyone agrees that the API design is horribly inconsistent. Still, it’s extremely easy to find out how to use stuff (easier than Python) - I have programmed professionally in Erlang, Python, Elixir and JavaScript and Erlang is the best. Of course, it might be because Erlang only really supports one programming paradigm (the actor model), but does that very well, and everything is designed around it… so it’s quite obvious why you want to do stuff (after certain level of competence).
4 Likes
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.
1 Like
@airakaz See this new topic for a thread that’s just on documentation.
use batteries, it has an excellent documentation.
1 Like
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:
2 Likes
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.
2 Likes
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.
1 Like
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:
https://github.com/boxed/pytest-readme
https://github.com/boxed/midje-readme
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.
@rizo there’s a design waiting to be implemented in odoc's issue tracker ;–) https://github.com/ocaml/odoc/issues/130
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 GitHub - samoht/mdx: Execute code blocks inside markdown files 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.
2 Likes
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.