From 10de355f86330eb48a4a8a0c1878e5a4064d7538 Mon Sep 17 00:00:00 2001 From: Ozzie Gooen Date: Fri, 3 Jun 2022 17:59:02 -0700 Subject: [PATCH] First attempt at auto-documentation --- .../FunctionRegistry_Core.res | 31 ++- .../FunctionRegistry_Library.res | 124 +++++++---- packages/website/docs/Features/Api.md | 199 ++++++++++++++++++ 3 files changed, 315 insertions(+), 39 deletions(-) create mode 100644 packages/website/docs/Features/Api.md diff --git a/packages/squiggle-lang/src/rescript/FunctionRegistry/FunctionRegistry_Core.res b/packages/squiggle-lang/src/rescript/FunctionRegistry/FunctionRegistry_Core.res index eed48ffc..b3e0c310 100644 --- a/packages/squiggle-lang/src/rescript/FunctionRegistry/FunctionRegistry_Core.res +++ b/packages/squiggle-lang/src/rescript/FunctionRegistry/FunctionRegistry_Core.res @@ -42,6 +42,9 @@ type fnDefinition = { type function = { name: string, definitions: array, + examples: option, + description: option, + isExperimental: bool, } type registry = array @@ -55,9 +58,9 @@ module FRType = { | FRTypeDistOrNumber => "frValueDistOrNumber" | FRTypeRecord(r) => { let input = ((name, frType): frTypeRecordParam) => `${name}: ${toString(frType)}` - `record({${r->E.A2.fmap(input)->E.A2.joinWith(", ")}})` + `{${r->E.A2.fmap(input)->E.A2.joinWith(", ")}}` } - | FRTypeArray(r) => `record(${toString(r)})` + | FRTypeArray(r) => `array<${toString(r)}>` | FRTypeLambda => `lambda` | FRTypeString => `string` | FRTypeVariant(_) => "variant" @@ -291,13 +294,34 @@ module FnDefinition = { module Function = { type t = function - let make = (~name, ~definitions): t => { + type functionJson = { + name: string, + definitions: array, + examples: option, + description: option, + isExperimental: bool, + } + + let make = (~name, ~definitions, ~examples=?, ~description=?, ~isExperimental=false, ()): t => { name: name, definitions: definitions, + examples: examples, + isExperimental: isExperimental, + description: description, + } + + let toSimple = (t: t): functionJson => { + name: t.name, + definitions: t.definitions->E.A2.fmap(FnDefinition.toString), + examples: t.examples, + description: t.description, + isExperimental: t.isExperimental, } } module Registry = { + let toSimple = (r: registry) => r->E.A2.fmap(Function.toSimple) + /* There's a (potential+minor) bug here: If a function definition is called outside of the calls to the registry, then it's possible that there could be a match after the registry is @@ -310,6 +334,7 @@ module Registry = { ~env: DistributionOperation.env, ) => { let matchToDef = m => Matcher.Registry.matchToDef(registry, m) + Js.log(toSimple(registry)) let showNameMatchDefinitions = matches => { let defs = matches diff --git a/packages/squiggle-lang/src/rescript/FunctionRegistry/FunctionRegistry_Library.res b/packages/squiggle-lang/src/rescript/FunctionRegistry/FunctionRegistry_Library.res index 6230f828..011e8b13 100644 --- a/packages/squiggle-lang/src/rescript/FunctionRegistry/FunctionRegistry_Library.res +++ b/packages/squiggle-lang/src/rescript/FunctionRegistry/FunctionRegistry_Library.res @@ -49,35 +49,10 @@ let inputsTodist = (inputs: array, makeDist) => { let registry = [ Function.make( - ~name="toContinuousPointSet", - ~definitions=[ - FnDefinition.make( - ~name="toContinuousPointSet", - ~inputs=[FRTypeArray(FRTypeRecord([("x", FRTypeNumeric), ("y", FRTypeNumeric)]))], - ~run=(inputs, _) => inputsTodist(inputs, r => Continuous(Continuous.make(r))), - ), - ], - ), - Function.make( - ~name="toDiscretePointSet", - ~definitions=[ - FnDefinition.make( - ~name="toDiscretePointSet", - ~inputs=[FRTypeArray(FRTypeRecord([("x", FRTypeNumeric), ("y", FRTypeNumeric)]))], - ~run=(inputs, _) => inputsTodist(inputs, r => Discrete(Discrete.make(r))), - ), - ], - ), - Function.make( - ~name="Declaration", - ~definitions=[ - FnDefinition.make(~name="declareFn", ~inputs=[Declaration.frType], ~run=(inputs, _) => { - inputs->E.A.unsafe_get(0)->Declaration.fromExpressionValue - }), - ], - ), - Function.make( - ~name="Normal", + ~name="Normal Distribution", + ~examples=`normal(5,1) +normal({p5: 4, p95: 10}) +normal({mean: 5, stdev: 2})`, ~definitions=[ TwoArgDist.make("normal", twoArgs(SymbolicDist.Normal.make)), TwoArgDist.makeRecordP5P95("normal", r => @@ -85,9 +60,13 @@ let registry = [ ), TwoArgDist.makeRecordMeanStdev("normal", twoArgs(SymbolicDist.Normal.make)), ], + (), ), Function.make( - ~name="Lognormal", + ~name="Lognormal Distribution", + ~examples=`lognormal(0.5, 0.8) +lognormal({p5: 4, p95: 10}) +lognormal({mean: 5, stdev: 2})`, ~definitions=[ TwoArgDist.make("lognormal", twoArgs(SymbolicDist.Lognormal.make)), TwoArgDist.makeRecordP5P95("lognormal", r => @@ -95,29 +74,43 @@ let registry = [ ), TwoArgDist.makeRecordMeanStdev("lognormal", twoArgs(SymbolicDist.Lognormal.fromMeanAndStdev)), ], + (), ), Function.make( - ~name="Uniform", + ~name="Uniform Distribution", + ~examples=`uniform(10, 12)`, ~definitions=[TwoArgDist.make("uniform", twoArgs(SymbolicDist.Uniform.make))], + (), ), Function.make( - ~name="Beta", + ~name="Beta Distribution", + ~examples=`beta(20, 25)`, ~definitions=[TwoArgDist.make("beta", twoArgs(SymbolicDist.Beta.make))], + (), ), Function.make( - ~name="Cauchy", + ~name="Cauchy Distribution", + ~examples=`cauchy(5, 1)`, ~definitions=[TwoArgDist.make("cauchy", twoArgs(SymbolicDist.Cauchy.make))], + (), ), Function.make( - ~name="Gamma", + ~name="Gamma Distribution", + ~examples=`gamma(5, 1)`, ~definitions=[TwoArgDist.make("gamma", twoArgs(SymbolicDist.Gamma.make))], + (), ), Function.make( - ~name="Logistic", + ~name="Logistic Distribution", + ~examples=`gamma(5, 1)`, ~definitions=[TwoArgDist.make("logistic", twoArgs(SymbolicDist.Logistic.make))], + (), ), Function.make( - ~name="To", + ~name="To (Distribution)", + ~examples=`5 to 10 +to(5,10) +-5 to 5`, ~definitions=[ TwoArgDist.make("to", twoArgs(SymbolicDist.From90thPercentile.make)), TwoArgDist.make( @@ -125,13 +118,72 @@ let registry = [ twoArgs(SymbolicDist.From90thPercentile.make), ), ], + (), ), Function.make( ~name="Exponential", + ~examples=`exponential(2)`, ~definitions=[OneArgDist.make("exponential", SymbolicDist.Exponential.make)], + (), ), Function.make( ~name="Bernoulli", + ~examples=`bernoulli(0.5)`, ~definitions=[OneArgDist.make("bernoulli", SymbolicDist.Bernoulli.make)], + (), + ), + Function.make( + ~name="toContinuousPointSet", + ~description="Converts a set of points to a continuous distribution", + ~examples=`toContinuousPointSet([ + {x: 0, y: 0.1}, + {x: 1, y: 0.2}, + {x: 2, y: 0.15}, + {x: 3, y: 0.1} +])`, + ~definitions=[ + FnDefinition.make( + ~name="toContinuousPointSet", + ~inputs=[FRTypeArray(FRTypeRecord([("x", FRTypeNumeric), ("y", FRTypeNumeric)]))], + ~run=(inputs, _) => inputsTodist(inputs, r => Continuous(Continuous.make(r))), + ), + ], + (), + ), + Function.make( + ~name="toDiscretePointSet", + ~description="Converts a set of points to a discrete distribution", + ~examples=`toDiscretePointSet([ + {x: 0, y: 0.1}, + {x: 1, y: 0.2}, + {x: 2, y: 0.15}, + {x: 3, y: 0.1} +])`, + ~definitions=[ + FnDefinition.make( + ~name="toDiscretePointSet", + ~inputs=[FRTypeArray(FRTypeRecord([("x", FRTypeNumeric), ("y", FRTypeNumeric)]))], + ~run=(inputs, _) => inputsTodist(inputs, r => Discrete(Discrete.make(r))), + ), + ], + (), + ), + Function.make( + ~name="Declaration (Continuous Function)", + ~description="Adds metadata to a function of the input ranges. Works now for numeric and date inputs. This is useful when making predictions. It allows you to limit the domain that your prediction will be used and scored within.", + ~examples=`declareFn({ + fn: {|a,b| a }, + inputs: [ + {min: 0, max: 100}, + {min: 30, max: 50} + ] +})`, + ~definitions=[ + FnDefinition.make(~name="declareFn", ~inputs=[Declaration.frType], ~run=(inputs, _) => { + inputs->E.A.unsafe_get(0)->Declaration.fromExpressionValue + }), + ], + ~isExperimental=true, + (), ), ] diff --git a/packages/website/docs/Features/Api.md b/packages/website/docs/Features/Api.md new file mode 100644 index 00000000..4955d498 --- /dev/null +++ b/packages/website/docs/Features/Api.md @@ -0,0 +1,199 @@ +--- +sidebar_position: 5 +title: API +--- +## Normal Distribution + +**Definitions** +```javascript +normal(frValueDistOrNumber, frValueDistOrNumber) +``` +```javascript +normal(dict<{p5: frValueDistOrNumber, p95: frValueDistOrNumber}>) +``` +```javascript +normal(dict<{mean: frValueDistOrNumber, stdev: frValueDistOrNumber}>) +``` + +**Examples** +```javascript +normal(5,1) +normal({p5: 4, p95: 10}) +normal({mean: 5, stdev: 2}) +``` + +## Lognormal Distribution + +**Definitions** +```javascript +lognormal(frValueDistOrNumber, frValueDistOrNumber) +``` +```javascript +lognormal(dict<{p5: frValueDistOrNumber, p95: frValueDistOrNumber}>) +``` +```javascript +lognormal(dict<{mean: frValueDistOrNumber, stdev: frValueDistOrNumber}>) +``` + +**Examples** +```javascript +lognormal(0.5, 0.8) +lognormal({p5: 4, p95: 10}) +lognormal({mean: 5, stdev: 2}) +``` + +## Uniform Distribution + +**Definitions** +```javascript +uniform(frValueDistOrNumber, frValueDistOrNumber) +``` + +**Examples** +```javascript +uniform(10, 12) +``` + +## Beta Distribution + +**Definitions** +```javascript +beta(frValueDistOrNumber, frValueDistOrNumber) +``` + +**Examples** +```javascript +beta(20, 25) +``` + +## Cauchy Distribution + +**Definitions** +```javascript +cauchy(frValueDistOrNumber, frValueDistOrNumber) +``` + +**Examples** +```javascript +cauchy(5, 1) +``` + +## Gamma Distribution + +**Definitions** +```javascript +gamma(frValueDistOrNumber, frValueDistOrNumber) +``` + +**Examples** +```javascript +gamma(5, 1) +``` + +## Logistic Distribution + +**Definitions** +```javascript +logistic(frValueDistOrNumber, frValueDistOrNumber) +``` + +**Examples** +```javascript +gamma(5, 1) +``` + +## To (Distribution) + +**Definitions** +```javascript +to(frValueDistOrNumber, frValueDistOrNumber) +``` +```javascript +credibleIntervalToDistribution(frValueDistOrNumber, frValueDistOrNumber) +``` + +**Examples** +```javascript +5 to 10 +to(5,10) +-5 to 5 +``` + +## Exponential + +**Definitions** +```javascript +exponential(frValueDistOrNumber) +``` + +**Examples** +```javascript +exponential(2) +``` + +## Bernoulli + +**Definitions** +```javascript +bernoulli(frValueDistOrNumber) +``` + +**Examples** +```javascript +bernoulli(0.5) +``` + +## toContinuousPointSet +Converts a set of points to a continuous distribution + +**Definitions** +```javascript +toContinuousPointSet(array>) +``` + +**Examples** +```javascript +toContinuousPointSet([ + {x: 0, y: 0.1}, + {x: 1, y: 0.2}, + {x: 2, y: 0.15}, + {x:3, y: 0.1} +]) +``` + +## toDiscretePointSet +Converts a set of points to a discrete distribution + +**Definitions** +```javascript +toDiscretePointSet(array>) +``` + +**Examples** +```javascript +toDiscretePointSet([ + {x: 0, y: 0.1}, + {x: 1, y: 0.2}, + {x: 2, y: 0.15}, + {x:3, y: 0.1} +]) +``` + +## Declaration (Continuous Function) +Adds metadata to a function of the input ranges. Works now for numeric and date inputs. This is useful when making predictions. It allows you to limit the domain that your prediction will be used and scored within. + +**Definitions** +```javascript +declareFn(dict<{fn: lambda, inputs: array>}>) +``` + +**Examples** +```javascript +declareFn({ + fn: {|a,b| a }, + inputs: [ + {min: 0, max: 100}, + {min: 30, max: 50} + ] +}) +``` \ No newline at end of file