Comments (17)
I prefer Style A, because then it should be easy to implement style B and C oneself
from carp.
I have strong opinions against both C and D, because they clutter up my definitions. I don’t like style B all that much, because style A looks the most consistent with a nice Lisp syntax.
How would one retrieve docstrings? I’d love to autogenerate some docs for my packages...
from carp.
What about separating documentation and type signatures?
Style D
Slightly modified style c.
;;; "Calculates the average value of an Array of double:s."
(defn average [nums]
(:: [(Array Double)] Double)
<implementation>)
Or any variation of doc/sig syntax.
from carp.
@yawaramin That looks pretty cool, I admit. It would be very similar to Style A though, just a bit more principled that you put everything at the top of the file. The fact that you can add both a type signature and a comment at the same time is pretty neat since it saves some noise.
What you're saying about forward lookup is true, it's a single pass compiler so it needs declarations for mutually recursive functions and the like.
Thanks for the input!
from carp.
Style A it is, coming up soon!
from carp.
I prefer Style C.
from carp.
Style C and D are harder to read imho, style A and B are both easier to read but as pointed out by @hellerve A looks Lispier.
A and B make me think of Elixir's @doc
and @spec
annotations, and I know I have a better time reading these rather than reading say Python doc where it's in the body of the functions. Not sure if it makes sense to compare these two with any Lisp-like language though.
from carp.
I am used to elisp, so I prefer style C... The docstring is then injected by defun. But the difference is that, functions here are static, yet functions in elisp are dynamically created.
from carp.
Thanks for the feedback everyone! I'll mull this over a bit. It will definitely be possible to access this information via dynamic functions. The compiler will also have a built-in doc exporter that can be invoked with a simple command to make it very easy to generate docs for libraries, both your own and others.
from carp.
Style C.
from carp.
I'd say we can borrow some ideas from Common Lisp, which has type declarations. I like the idea of separating out declarations from the implementation in the general case. This keeps the implementations succinct. But we also need a way to annotate an expression with a given type, to enforce our idea of what the type should be.
For declarations we can do something similar to CL's declare
, type
, and ftype
: http://clhs.lisp.se/Body/d_ftype.htm#ftype
(export ; Should go at the top of a Carp module
(type Person () "Opaque type example.")
(type Aggregate (function [(Array Double)] Double) "A function that aggregates an array of doubles into summary statistic.")
(value average Aggregate "Calculates the average.")
(value min Aggregate "Calculates the minimum.")
(value max Aggregate "Calculates the maximum.")
For type annotations we can simply reuse the above (value ...)
form). Without export
, value
can annotate a given expression with the given type, with an optional docstring.
The benefit of type declaration is that it also enables forward lookup (if it is present). Although I don't know Carp's design in that respect, i.e. does it do forward lookups already like Haskell, or does it require all names to be declared before use like OCaml.
from carp.
I would suggest update of the
form and swapping it's arguments around with an option to add docstring:
Style E
;; Without comment string
(the average (λ [(Array Double)] Double))
(defn average [nums]
<implementation>)
;; With comment string
(the avarage
"Calculates the average value of an Array of double:s."
(λ [(Array Double)] Double))
(defn average [nums]
<implementation>)
Edit: You could possible allow optionally inline implementation as well (assuming such fn
could be added):
(the avarage
"Calculates the average value of an Array of double:s."
(λ [(Array Double)] Double)
(fn [nums]
<implementation>))
from carp.
If overloading the
(or introduction of it with different name say :
or type
) does not seem like good option my vote would be with Style A as I very much value ability to separate type annotations from implementation.
from carp.
my preferences would be style A then B then D then C.
A because not extra nesting, (can write signature at top level)
B for same reason.(less lispy)
D goes before C because in many languages that is more common!
and i really dont like C because that the general style other languages go with
from carp.
@eriksvedang how is it going to look for inner functions (lambad & closures) ?
from carp.
They will use the current (the <type> <expr>)
syntax that's already implemented.
from carp.
This is in now! There are still bugs and features missing but the general idea works so I’ll close this.
from carp.
Related Issues (20)
- Bug with REPL displaying result of calling function that returns Char HOT 1
- REPL prompt is not `鯉` on Linux HOT 2
- (()) seems to cause an infinite loop on the latest release
- Packaging issues. HOT 1
- `format` leaks memory HOT 1
- `--eval-preload` does not have access to Core anymore HOT 6
- [Bug] Not handling all cases during pattern-matching in lambdas HOT 8
- [Bug] Control.iterate-until double-uses a variable, and thus is broken HOT 3
- [Feat Request] Exhaustive pattern-matching for `defn` HOT 5
- [Bug] Issue pattern matching structs HOT 7
- Document println*
- Feature Request: Make running tests not dependent on stack?
- CarpHask fails to build with hashable >= 1.4 (GHC 9.2 / Stackage LTS-20) HOT 4
- FR: Better Support for Embedded HOT 5
- Get Can't find symbol 'make-update-deriver' when trying to run example on Windows 11 HOT 7
- [bug] duplicate bindings in environment HOT 2
- Repl crashes on type of Map
- Repl :t command doesn't work with (use) HOT 3
- Is Carp still maintained? HOT 2
- Trying to compile nested let takes up a lot of resource
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 carp.