Show type with #doc

[hcarty]

I'm not sure if it makes sense to have this be something that's configurable or have multiple #-commands to enable this. Doc strings often assume the context of a function or value's type. It would be nice, if possible, to have #doc show both.

This can be done currently, of course, with #show then #doc but it would be nice to have this all in one step.

[reynir]

Thanks for the suggestion. I have had the same thoughts, but I have not implemented printing types partly out of laziness partly because of the overlap with the #show directive. I'm open for adding the type in #doc, and it would make it more similar to how ocp-index print works:

$ ocp-index print List.find
List.find val ('a -> bool) -> 'a list -> 'a
    [find p l] returns the first element of the list [l]
    that satisfies the predicate [p].
    Raise [Not_found] if there is no value that satisfies [p] in the
    list [l].

I will not be implementing this just yet - but patches are most welcome!

[reynir]

The latest version prints the type. However, I realize now that maybe sometimes it's unwanted. When running the directive on modules it can be quite noisy since the whole module signature is printed. I think that in most cases it's more useful than not, though.

# #doc Nocrypto.Rsa;;
Nocrypto.Rsa module
  sig
    exception Insufficient_key
    type pub = { e : Z.t; n : Z.t; }
    type priv = {
      e : Z.t;
      d : Z.t;
      n : Z.t;
      p : Z.t;
      q : Z.t;
      dp : Z.t;
      dq : Z.t;
      q' : Z.t;
    }
    type mask = [ `No | `Yes | `Yes_with of Rng.g ]
    val pub_bits : pub -> int
    val priv_bits : priv -> int
    val priv_of_primes : e:Z.t -> p:Z.t -> q:Z.t -> priv
    val pub_of_priv : priv -> pub
    val encrypt : key:pub -> Cstruct.t -> Cstruct.t
    val decrypt : ?mask:mask -> key:priv -> Cstruct.t -> Cstruct.t
    val generate : ?g:Rng.g -> ?e:Z.t -> int -> priv
    module PKCS1 :
      sig
        val sig_encode : ?mask:mask -> key:priv -> Cstruct.t -> Cstruct.t
        val sig_decode : key:pub -> Cstruct.t -> Cstruct.t option
        val encrypt : ?g:Rng.g -> key:pub -> Cstruct.t -> Cstruct.t
        val decrypt : ?mask:mask -> key:priv -> Cstruct.t -> Cstruct.t option
      end
    module OAEP :
      functor (H : Hash.S) ->
        sig
          val encrypt :
            ?g:Rng.g -> ?label:Cstruct.t -> key:pub -> Cstruct.t -> Cstruct.t
          val decrypt :
            ?mask:mask ->
            ?label:Cstruct.t -> key:priv -> Cstruct.t -> Cstruct.t option
        end
    module PSS :
      functor (H : Hash.S) ->
        sig
          val sign :
            ?g:Rng.g -> ?slen:int -> key:priv -> Cstruct.t -> Cstruct.t
          val verify :
            ?slen:int -> key:pub -> signature:Cstruct.t -> Cstruct.t -> bool
        end
    val pub_of_sexp : Sexplib.Sexp.t -> pub
    val sexp_of_pub : pub -> Sexplib.Sexp.t
    val priv_of_sexp : Sexplib.Sexp.t -> priv
    val sexp_of_priv : priv -> Sexplib.Sexp.t
  end
    {b RSA} public-key cryptography.
    
    Keys are taken to be trusted material, and their properties are not checked.
    
    Messages are checked not to exceed the key size, and this is signalled via
    exceptions.
    
    Private-key operations are optionally protected through RSA blinding.

#