document Identifiable module about base HOT 10 CLOSED

Imagine someone new to OCaml and Core, and they look at this mli. They're just lost. The example you gave is perfect; that would be excellent documentation. The fact that you get an abstract type that is otherwise the same as an existing type is really useful, and I imagine lots of people won't see that right away.

from base.

I'm weirdly at a loss for words. These are just the set of properties that we routinely want out of values used as simple identifiers, in lots of different contexts. Stringable, Pretty_printer and Sexpable are important for being able to show these identifiers to users; Comparable and Hashable are important for using them as keys in maps and hashtables.

I'm oddly not sure what else to add to the comment to clarify...

from base.

Ok so maybe it is just that simple, but no reason that couldn't be the documentation then: "This module type represents a collection of function signatures that are frequently useful together. For example, we include this signature in modules Foo, Bar, and Baz". This not useless. It saves users a few minutes trying to figure out if there is some more important purpose. (These minutes add up. I posted this issue only as an example. The whole Core/Async suite has over a hundred modules. Most people don't know which ones to understand first, and which are less important.)

Another question that could be answered is: why should anyone use this module? I genuinely don't see the point of it. I happily include Stringable, Sexpable, etc, separately in places I want to support those signatures. Why should I choose Identifiable; is it just to save a bit of typing and reduce 5 include lines with 1? Good enough reason if that's it, but point is I don't immediately know that to be the case. Why not just tell us that if that's it.

I still don't see what is "identifiable" about it, that it can be printed or tested for equality? "Identifiable" could mean that uniqueness is somehow assured. That is clearly not so (after spending a minute looking at the signature), so again a little explanation could save everyone some minutes.

from base.

I think the utliity is pretty clear. If I want a new abstract identifier based on strings, I can just write:

module Session_id : Identifiable = String

and I'm good to go. Bundling together a very commonly used set of functionality into a single standard is quite useful. Also, we write lots of functors that demand that thier inputs are Identifiable. At a glance, I see about 1200 use-cases in our tree.

Anyway, I'll add a few more lines of documentation to make the purpose of the API clearer.

from base.

The Make functor destructively removes the abstract type, and the example given doesn't accomplish what your simple example does. So I'm unsure what its use case is. I also just now realized that Identifiable is provided as both a module type and module. I also don't know what module_name is needed for. I feel there's plenty that could be explained!

from base.

The functor does actually have a comment, with an example:

(** Used for making an Identifiable module.  Here's an example.

    {[
      module Id = struct
        module T = struct
          type t = A | B [@@deriving compare, hash, sexp]
          let of_string s = t_of_sexp (sexp_of_string s)
          let to_string t = string_of_sexp (sexp_of_t t)
          let module_name = "My_library.Std.Id"
        end
        include T
        include Identifiable.Make (T)
      end
    ]} *)

This creates a module that satisfies the Identifiable interface. It doesn't make it abstract. To do that. To do that, you need to put something into the mli. This is a fundamental thing about the language, and this doesn't feel to me like the right place to document it.

from base.

Some more extended documentation has now been released.

from base.

Thanks. I appreciate you spending time on an issue that you clearly feel didn't deserve any.

I also don't know what module_name is needed for.

I stand corrected on this. This was already documented.

from base.

from base.

I hope the current docs are an improvement!

Yes, it is definitely helpful. But to be honest an important example that would really help is missing and an obvious question that everyone surely will have remains unanswered. I could expand but I feel I'll just be further harassing you on a point that is at once not really worth more of your time, and on the other hand so big that we can't resolve it over GitHub.

from base.