Create spec

[Paul Biggar]

I've been thinking through multiple iterations of how we'd spec functions, including #307, #288 and #299. This idea maybe solves all three.

We should have a set of yaml files, one for each function. These files would specify the function name, the module, test cases, examples, docstrings, parameter types and names. Basically, anything which is useful for automatically generating tests, docs, templates, etc.

For example, we could have Int.add.yaml, with the following contents:

module: Int
name: add
docstring: Add <param a> to <param b>, returning their sum
parameters:
  - name: a
    type: int
  - name: b
    type: int
returnType: int
# For compatibility
constraints:
  - no-ocaml
  - no-rescript
tests:
  - inputs: [1,2]
    output: 3
  - inputs: [1,1]
    output: 2
examples:
  - inputs: [1,2]
    output: 3
  - inputs: [1,1]
    output: 2
added: 0.1.0 # We can use 0.1.0 for all of these for now

Given this, we can add some scripts in rescript that reads these and generates:

• test files for each language
• a markdown page with tests, docstrings and compatibility
• interface files for each language

Possibly there would be one script that accepts format strings so we could reuse it to do all this, but that's just an idea.