I’ve always relied on loading the .mli files in the editor (Vim).
For a long time this was :sfind bigarray.mli (with a path including ocaml source); with merlin it’s :MLI bigarray, but after the stdlib restructuring, this particular invocation gives me an unhelpful stub including Stdlib.Bigarray.
I can see that the actual bigarray.mli is in a deeper nested directory in opam with the source. Adding that to my search path seems potentially fragile with version bumps. So I’ve just been working around the issue (opening the specific file) when it occurs.
And I guess the trigger to my asking about this now is the recent announcement of wonderful web-based module documentation. It makes me wonder: what do you do when your programming in OCaml and want to check documentation for a particular (installed) module?
I’m wondering if I’m missing out on something. Or, if others load local mli files as I do… how to nicely get the correct mli (and not a Stdlib stub). ie. When normal things don’t work… I begin to suspect what I’m doing isn’t normal anymore.
Oh man… nice to know that works. Has the advantage of being formatted rather than being littered with format cues, while still being readily viewed in-editor. Thanks, I might start using that.
If I am in my editor I’ll use merlin/lsp “go to definition” on the module and hopefully it jumps to the mli file. Works for modules already imported properly into merlin.
Usually I know in which package PKG it is so I simply:
odig doc PKG
I always wanted to add more specific queries to odig (e.g. by module name, by identifier) but never got to do it (maybe lazily waiting for that odoc issue to resolve :-).
Handy when you have an available reference! My problem here is that while writing I’m often looking for something without having a suitable nugget to select as a “get me more info about this”. Scanning the screen for a reference, aborting and then typing something into my source to use and then undoing it afterward feels clunky (worse-case scenario, but not uncommon for me). While reading or working with someone else’s code though, this works wonders.
I’ve seen you mention odig a bit, and I’ve looked at the github page… but I still don’t entirely know what to expect, so haven’t tried it.
It says command-line, so it has it’s own terminal-based viewer? Similar to man or texinfo? But I don’t know. The examples, of course, are webpages… which look nice and offer (refreshing for me) darker themes… but web-browser as programming-reference doesn’t appeal. Also, I’m confronted primarily by package info, which rarely interests me, and API is another step away. I’m sharing this viewpoint as one looking from outside – this is what I see, but maybe my impressions are wrong. Maybe I should just opam install it instead of blathering on.
No it’s web pages. Basically it generates this for your current opam switch and provides a few cli commands to quickly get to the readme or changes of a package (see the quick start here)
But I once tried it in a text only browser (emacs’ eww) and the result was not too bad (if you encouter problems in that mode, do open issues on odoc)
Honestly I never really understood how people cope with manpages for “programming-reference”, it’s totally unconvenient. Hypertext is king for documentation (cross refs!). I usually simply have a webrowser sitting next to my editor (because I anyway write and render a lot of said doc and do quite a bit of webly stuff).
Not sure what you are mentioning here. If you do odig doc PKG you get on a page which either has all the modules of the package listed for your clicking pleasure or a presentation of them left to the discretion of the package authors if they provided an index.mld file.
So I gave manpages a whirl… while the text is cleaner (than .mli), this is pretty minor, and I realize I’m mostly interested in quickly parsing types/signatures, which lack syntax highlighting with man.
@dbuenzli Okay, you have me considering maybe a minimal-frame browser window. I think we are all probably just familiar with different workflows, and it can be hard to give something different a fair-analysis without trying to make it work.
I also find man pages harder to read due to limited highlighting (the lack of hyperlinks doesn’t bother me as much; years of practice with this venerable Unix relic got me used to navigate man pages… manually). Plus, in the past at least, OCaml’s man page rendering was buggy (not sure if fixed, I could not reproduce in a few seconds right now), and they remain ill-formatted.
But the practicality of man pages remains a rather theoretical question since, in practice, I don’t remember having ever managed to get man pages for anything but the standard library and standard CLI tools (and some others such as dune or utop). Either no library author provides them, or I am ignorant of a way to obtain them with opam.
(FWIW, local HTML documentation using odig/odoc rocks.)
In my doc strings and .mld manuals I do actually try to structure a meaningful and useful hypertext. I find it a bit sad that all this work gets destroyed by a subpar documentation medium. It’s even worse than that, sometimes the docs may not make sense without the hyperlinks, the text is written with them in mind.
So while odoc recently got the ability to generate man pages I have no plans to support that in odig because from my point of view man pages breakocamldoc documentation.
For the purpose of reading documentation in the terminal, might info be a more relevant medium? I believe it has hyperlinks? (I might be wrong, I really never used it as it needs more learning than man, alas.) I have no idea whether support for it already exist somewhere in the OCaml world.
info would certainly be an option but rather than lose our time supporting all the documentation formats out there, I’d rather suggest to spend the limited energy to ensure the HTML generated by odoc is accessible and provides a good experience in text-based web browsers.
It will likely lead to an overall better terminal user experience. For example if you take brr's docset, doc strings often forward to MDN Web docs which won’t be infoed. With a text-based browser you’d seamlessly browse from your local brr docset to MDN and back.
I mostly open the .mli. I actually find it annoying that modern OCaml code tends to rely on
‘include’ that makes this task more difficult. A nice documented flat .mli is a great resource. See for example dream/dream.mli at master · aantron/dream · GitHub
I remember in C/C++ I needed tools like doxygen, because C/C++ header files were just horrible. I loved it when starting OCaml to have those nice simple .mli. We start to need tools for OCaml because we abuse ‘include’ and module aliases and functors and so on. KISS, so you don’t need tools!
