Feedback wanted – Docs and type signatures

[carp-lang]

Feedback wanted – Docs and type signatures

[porky11]

I prefer Style A, because then it should be easy to implement style B and C oneself

[hellerve]

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...

[Nananas]

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.

[eriksvedang]

@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!

[eriksvedang]

Style A it is, coming up soon!

[jiegec]

I prefer Style C.

[evuez]

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.

[jiegec]

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.

[eriksvedang]

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.

[devn]

Style C.

[yawaramin]

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.

[Gozala]

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>))

[Gozala]

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.

[warlord500]

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

[Gozala]

@eriksvedang how is it going to look for inner functions (lambad & closures) ?

[eriksvedang]

They will use the current (the <type> <expr>) syntax that's already implemented.

[eriksvedang]

This is in now! There are still bugs and features missing but the general idea works so I’ll close this.