Code readability - How to view signature and documentation of a module?

Learning
, , ,
#1

I wrote this line:

module Tbl = Core_kernel.Std.Hashtbl.Make (Bap.Std.Exp)

For the sake of generality, let’s rewrite this as:

module Out = Lib.Make (In)

What is a good, systematic way of viewing the signature and the documentation of the modules Out and In, and of the functor Lib.Make?

The person viewing the code being…

  • someone who’s unfamiliar with OCaml and who doesn’t have a development environment set up, e.g. someone browsing code on GitHub?
  • someone having the best OCaml development environment set up for them?
2 Likes
#2

Excellent question!

For this one, the answer is interface documentation generation. The odoc tool does cross-referenced documentation, and is something we (@antron in particular) are actively working on to build a central docs.ocaml.org repository where the above interfaces could be browsed. As an example the current (beta) version of odoc running on the MirageOS modules and cross-referencing them can be found at http://docs.mirage.io.

As odoc gets more complete in the coming months, we’ll post on this forum to get your feedback on that.

Merlin should be able to show you all the relevant interfaces from within your editor. Have you given it a spin?

3 Likes
#3

I second Merlin: using it via Visual Studio Code is great.

3 Likes
#4

So far VS Code with the Reason/OCaml extension with Merlin looks amazing. I’m on Ubuntu Linux and I’d be switching over from ~20 years of emacs.

4 Likes
#5

Yes, but it doesn’t work from emacs or the function that does it is buried somewhere and I couldn’t identify it. It works in Visual Studio Code (MIT license, runs on Linux/Mac/Windows) which I just tried out and it’s great.

#6

Do you know ocp-browser?
Not sure it does exactly what you want though.

#7

Just in case you’re still wanting to stay at emacs world, the Merlin wiki of emacs from scratch documents the functions quite well, and you can use opam-user-setup to simplify the setup when using multiple switches. Or, in case readers are interested in Spacemacs, it’s only a matter of adding the ocaml layer (also includes Spacemacs installation instructions).

2 Likes
#8

ok, so I found out what I was doing wrong. I had this in my .emacs:

; huh, C-c C-t is overridden by ocp-index-print-info-at-point,
; which kind of does the same thing but misses some type info.
(global-set-key (kbd "C-c t") 'merlin-type-enclosing)

which is probably wrong in more than one way. The main problem is that it overrides the original “C-c t” shortcut that would let me see the type of a module.

After commenting out the above, “C-c t” shows me the signature of the module under the cursor in another buffer, which is great. And “C-c C-t” is back to calling ocp-index-print-info-at-point which doesn’t fully work and often blocks for several seconds.

For the record, the problematic behavior happens after leaving just this in my ~/.emacs:

;; ## added by OPAM user-setup for emacs / base ## 56ab50dc8996d2bb95e7856a6eddb17b ## you can edit, but keep this line
(require 'opam-user-setup "~/.emacs.d/opam-user-setup.el")
;; ## end of OPAM user-setup addition for emacs / base ## keep this line

The instructions I think I followed and turned into a script for setting up emacs for OCaml development are:

opam install -y merlin
opam user-setup install
opam install -y ocp-indent ocp-index

# emacs only
opam install -y tuareg

Am I installing too much? Did I start from a dirty state? Maybe. The point is that it’s hard to tell.

#9

Update: now merlin-type-enclosing works for me on module names as well. I have no idea why.