Comments (3)
While I was reading the previous discussion, I saw #12309 (comment). It made me think about what pushing the syntax early in the relevant manual section conveys.
Wouldn't this be messaging that it's more of a mature feature despite the note in the beginning? The syntax on its own already lowers the barrier of usage (e.g. you now don't have to manually specify and wire the effect's type variable through in the handler).. using it as the default in documentation material becomes more of a soft endorsement I imagine. It would be the case for me if I was reading the manual & not aware of the wider context around the feature and its current stage of development. I'd be more tempted to design things using it, taking the note I mentioned to mean that just the API is in flux, not the semantics of the feature itself.
The messaging from you maintainers here in development discussions seems to be that we shouldn't use effects and their operations directly in everyday code.. instead using abstractions built on top of them which cover raw performs, handlers, and the effect constructors. Also that the feature itself can be subject to massive reworking, that it's not mature nor frozen in its current form. The manual would nudge it towards being more complete and satisfactory, with the evidence being its elevation from library API to syntax, and the use of that syntax by default in examples.
Maybe the note in the beginning should be elevated to a warning or the experimental nature be more visually emphasized, to balance things out. Maybe the syntax form should be pushed lower in the page, or just mentioned in the lexical definitions of the relevant constructs without changing the examples. Maybe I'm overthinking it. I don't know. What do you think?
from ocaml.
Imho the user manual is not the place to be making editorial decisions about what parts of the language are encouraged or discouraged. It should clearly document the language as is.
from ocaml.
The manual isn't a formal spec. There are lots of soft parts with subjective wording that influence how a feature is approached,
what parts of the language are encouraged or discouraged
and precedent for this actually, as suggestions for idiomatic approaches, or as implicit nudges to make the reader aware of common gotchas, as I imagine this would be too.
from ocaml.
Related Issues (20)
- Regression with default GC settings between `4.14.2` and `5.1.1` HOT 7
- Doc typo in `Printexc` HOT 2
- Abnormal exit after upgrading to OCaml 5 HOT 4
- Restore native armv7 support for NetBSD 10.0 HOT 7
- Missing warning when an attribute is ignored or makes no sense HOT 9
- Support parameter constraints in module signature type equalities HOT 5
- Simplify effect handler closure and reperform by dropping the `last_fiber` argument
- Module type substitutions in signature of recursive modules are not checked for cyclicity
- Sub-module identities inside an applicative functor are actually generative, leading to invalid signatures
- Strange error message with trunk HOT 5
- "β t is less general than ∀α. α t" with trunk HOT 14
- Please provide guidance whether the static linking exception applies to distributions like DkML HOT 12
- Semantics of toplevel let-bindings in classes HOT 12
- Make extensible variants more efficient and mashalable. HOT 4
- Library archive name change in OCaml 5 (e.g libunix.a -> libunixbyt.a & libunixnat.a) HOT 3
- Type-level module alias for functor parameter accepted HOT 1
- Signal handler doesn't run if signal received at the wrong time
- Stdlib: `Dynarray.insert` procedure HOT 5
- Buggy exhaustiveness check when defining types inside a module HOT 2
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 ocaml.