Comments (10)
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.
Related Issues (20)
- List functions requiring same length arguments have runtime dependent on longest argument HOT 4
- Unable to build v0.15~preview.125.13+424 HOT 4
- OCaml 5.00 support HOT 1
- int_math_stub.c should use BitScanReverse for clz (and BitScanForward for ctz) HOT 1
- Core.List.exists doesn't work as expected HOT 1
- Support for non-empty lists HOT 4
- Difference between `base`, and `core_kernel`? HOT 2
- Cannot build on system with only ocaml and dune installed. HOT 1
- Please don't auto-register printers for exceptions defined outside of Base HOT 2
- Map.update changes the "physical" key in certain circumstances HOT 1
- What is the policy regarding support for older OCaml versions ? HOT 3
- Base v0.16.0 build failure on windows HOT 2
- make List.take return physical identity for n = length HOT 1
- Linker error on macOS with base 0.16.1 HOT 3
- v0.16.2 is broken with MSVC on Windows HOT 3
- Use `write-file` instead of `bash` in dune action HOT 1
- No docs HOT 2
- Add String.to_sequence (the standard library has String.to_seq)
- Allow for libraries depending on base to enable dune's (implicit_transitive_deps false) HOT 2
- Segmentation fault with `String.filter_map` HOT 3
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from base.