Maybe if it’s to be an effort of the core team, I think you’re right. Just to lean on prior experience tho: if a clojuredocs model were pursued, that could start immediately, be well underway within the year, and if those responsible for ocaml.org were amenable, could be a source for addendums spliced into the official docs at whatever pace they preferred.
I could be wrong, as I don’t know the history, but that (clojuredocs model) sounds like a similar rational for OCamlVerse. I.e., a lower barrier of entry for docs and wiki-ish style stuff. And that seems to have worked pretty well, too.
Yup, very analogous. OCamlverse may well be a good place for a parallel documentation/examples effort.
When I was reading OCaml from the very begining, I did feel that the stdlib could be a little more documented.
This feeling comes from expectations, having seen other ecosystems.
This is OCaml:
This is Elm:
This is Rust:
It didn’t come to mind to bother anybody with this but since you seem to be open to such improvements, what would be the process to contribute those little snippets/examples?
(considering this PR has been long merged and didn’t cover the above)
IMO, such little documented examples would make the overall OCaml experience “better”. Although of course this is just a subjective matter.
I don’t understand why people prefer partial specifications (i.e. examples with constants) over equations.
You will never read code that reads like elm’s sample code. I don’t think it helps understanding the essence of a List.fold_left
when you find it in situ in a real program.
I find OCaml’s doc string vastly superior as it enables equational reasoning. These partial specifications are like testing, you just get to understand (if at all) how it behaves on a few cases and miss the corner ones.
Speaking of which I note that none of the docstrings (OCaml’s one included) indicate you what happens on the empty list.
This is a very nice user-story-esque way of presenting the relative deficit in this department.
I don’t think it’s one over the other. An example can be used as a complement, to aid the overall understanding of a function that’s all.
For info the Rust doc is actually much longer, I was merely pointing to my area of interest.
That’s not the point of code examples. The point is to help quickly build up the reader’s intuition, not to show what it looks like in a ‘real’ program. Not everyone grasps a function immediately through equational reasoning. A lot of people usually need to build up to it by grasping smaller, more specific examples first, then building up the intuition for the general function.
I think we disagree on what reference documentation is for. I’m looking for specifications and how code is supposed to be read in reference documentation.
There’s plenty of other places where you can show how to work with functions on specific examples and how to combine them in useful manners.
And if you need to grasp a function through more specific examples then nothing beats firing up your toplevel and make your own examples.
I also think we should have more material to teach equational reasoning to newcomers, they would maybe be able to see more value in the current style of documentation, part of the struggle is a cultural one.
Why not both? I don’t think it would hurt anything if reference materials were provided as the initial part of the comment and then simple examples as the latter part which more advanced readers would just skip or collapse/fold in some viewers/editors.
I get that not having examples is your preference but it’s not really a mainstream view for reference documentation. E.g. take a look at man jq
and man curl
, these are chock-full of examples, and these are man pages, it’s about as ‘reference’ as it gets
Giving examples with constants for individual functions may or may not be useful (I completely understand the desire to have a precise definition).
But examples areuseful at a module level though, not because it explains how the function works, but shows you examples of how they are meant to be combined, and in what situations they would be useful to use.
E.g. Cmd (bos.Bos.Cmd) documents what the on
function does, and if that is all it contained then it’d be an exercise to the reader on when that might be useful to use.
But presumably the author had a consistent design in mind that would show what the advantage of having that kind of function would be (depending on the user’s experience they may realize on their own sooner or later how that function might be useful or not), and indeed the example section does show one such case:
Cmd (bos.Bos.Cmd)
let ocamlc ?(debug = false) file =
Cmd.(v "ocamlc" % "-c" %% on debug (v "-g") % p file)
And then your user would (hopefully!) realize: on
is a nice way of conditionally inserting concise snippets of command line arguments, without having to write a lot of if
/match
, or Option.map
code.
The value here isn’t in the constants used to invoke the function, but on how to use the various pieces together. That usage may seem trivial (or even implicit) to the author, but is very helpful to have for users.
As for the standard library a good place where more examples might be useful is explaining the various design choices and how to take advantage of them. E.g I appreciate the |>
example in the [Map]](OCaml library : Map) documentation, a short explanation somewhere might be nice that the order of arguments in Map was specifically chosen to make this kind of usage easier.
And it’d also explain why Hashtbl took the opposite choice: you don’t need to ‘pipeline’ through an imperative data structure, whereas you need to for a purely functional one. When I started learning OCaml I always found it confusing why one module got one order of arguments and the other one the opposite…
Because there’s value in conciseness and focus.
It’s not that it’s not my preference. I think examples have their place but not directly in doc strings.
Maybe because they are confusing tools :–) ?
In fpath’s docs I added a lot of examples which I link from the doc strings (and which sadly odoc
still half-garbles because of this issue). The reason is that the notion of file system path is an utterly confusing (or broken, at your wish) one. It’s impossible to convey concisely what happens on relative segments and other trailing slashes.
So maybe if you need to add examples in your doc string it’s because your function specification is confusing. So review the function rather than add examples ;–)
I think we are playing around with words here, it’s understood in the context of this thread that we are talking about examples in docstrings.
Maybe because they are confusing tools :–) ?
How confusing is too confusing?
Look at man date
, there’s a whole section of examples. Surely the date
command isn’t at the same level of complexity as jq
and curl
? In any case, that wasn’t even my point. My point is that it is already well understood and idiomatic for reference materials to include examples of usage. I know that you don’t find it valuable, but it’s important to acknowledge that it’s very common and people do find it helpful.
Indeed man page have an EXAMPLES
section, that’s precisely what I’m advocating for.
It seems you neither read nor know me well… I just linked you to a library of mine that is full of examples . We are just disagreeing on how these should be designed and organized.
fwiw, haskell’s docs have both the equational documentation and the instances in examples. I jumped to check those because I’m used to seeing equations in their docs, they even have nice LaTeX rendering for notation like Big-O etc. And I was curios to see whether they augmented with examples.
cc @dbuenzli : examples are their own (folded) section. I think this is nice for all parties
Foul! Those are commands, i.e. programs. Try e.g. 'man strcmp`. No examples. You cannot generalize over EXAMPLES in manpages; some have them, some don’t.
A fair point, and you made me immediately think of the C++ documentation. Have you see this?
https://cplusplus.com/reference/vector/vector/vector/
Gotta say, this is just incredibly useful. I don’t need to keep the usage details of a gazillion C++ functions/classes/templates in my head: just vague ideas of the names, and I can lookup the rest.
Again, that was not my point. I wasn’t saying that all man pages include examples, only that many do, and that it’s normal for reference documentation to include examples.
I was going to beat you up about your previous “I don’t understand why people prefer partial specifications (i.e. examples with constants) over equations.” but you clearly unnerstand the issues. I daresay 99+% of working programmers would respond to “equational reasoning” with a hearty 'WTF???". But you know that, obviously,
“Equational reasoning” is a phrase that would get your ass kicked the bars I hang out in. Not that I hang out in bars, I’m just sayin. Seriously, it is a very arcane concept. The notion of “equality” is astonishingly complicated. But no practicing programmer who needs to get shit done cares about the subtleties.
But equational reasoning is essential, so as you suggested it needs to be covered in the docs.
I’ve encountered highly competent programmers who are not just indifferent to theory, but actively hostile to it. They just want to get stuff done, and they consider theoretical stuff (“equational reasoning”) mere noise that gets in the way. And for most languages, they’re right. Do you really need theory to master python programming? No. In fact you would probably suck if you felt the need to justify your python code by mapping it from some kind of theory.
But OCaml is different, IMO. It is one of the few (only?) practical languages in which the path from theory to practice is both direct and perspicuous. I think that a Good Thing, without reservation. But it does mean that documentation also has different requirements.
Most conspicuous example: the module concept. This is, IMHO, the heart of OCaml. You cannot write Ocaml code without writing a module. But, bizarrely, most intros to OCaml treat modules as an afterthought. If I had the time to write “Intro to OCaml” I would surely start with modules.
To get back to the original question, which is essentially “why do the OCaml docs suck?”, I have the following admittedly lame suggestions:
- There is no “The OCaml Language:: Concepts” document, and there should be
- The official “manual” is an unholy mess that does not sufficiently distinguish between language concepts and toolchain concepts.
- all the other stuff
Point of comparison:
https://developer.arm.com/documentation/ddi0596/2021-12/?lang=en