Flux function type signatures (#4138)

* adds flux type signature documentation

* updates to type signature doc

* renamed type signature doc

* udpated type signatures doc to address PR feedback

* last few updates to type signature doc

content/flux/v0.x/data-types/basic/regexp.md

@@ -1,17 +1,24 @@
 ---
 title: Work with regular expression types
 seotitle: Work with Flux regular expression types
-list_title: Regular expression types
+list_title: Regular expression
 description: >
+  A **regular expression** type represents a regular expression pattern.
   Learn how to work with Flux regular expression types.
 menu:
   flux_0_x:
-    name: Regular expression types
-    parent: Work with Flux types
-weight: 101
+    name: Regular expression
+    parent: Basic types
+weight: 201
 flux/v0.x/tags: ["regexp types", "data types"]
+aliases:
+  - /flux/v0.x/data-types/regexp/
 related:
   - /flux/v0.x/stdlib/regexp/
+list_code_example: |
+  ```js
+  /^[a-z0-9]+$/
+  ```
 ---
 
 A **regular expression** type represents a regular expression pattern.
@@ -30,7 +37,7 @@ This syntax is similar to regular expressions in Perl, Python, and other languag
 Regular expression literals are enclosed in forward slash characters (`/`).
 
 ```js
-/^[a-z0-9]{1,}$/
+/^[a-z0-9]+$/
 ```
 
 ## Use regular expression flags

content/flux/v0.x/data-types/basic/string.md

@@ -71,7 +71,7 @@ string(v: 42)
 ```
 
 ### Convert regular expressions to strings
-To convert a [regular expression](/flux/v0.x/data-types/regexp/) to a string:
+To convert a [regular expression](/flux/v0.x/data-types/basic/regexp/) to a string:
 
 1. Import the [`regexp` package](/flux/v0.x/stdlib/regexp/).
 2. Use [`regexp.getString()`](/flux/v0.x/stdlib/regexp/getstring/) and provide

content/flux/v0.x/function-type-signatures.md

@@ -0,0 +1,214 @@
+---
+title: Function type signatures
+description: >
+  A **function type signature** describes a function's input parameters and
+  types, and the function's output type.
+menu:
+  flux_0_x_ref:
+    name: Type signatures
+weight: 10
+related:
+  - /flux/v0.x/data-types/
+  - /flux/v0.x/spec/types/#type-constraints, Type constraints
+---
+
+A **function type signature** describes a function's input parameters and types,
+and the function's output type.
+Use type signatures to identify data types expected by function parameters and
+to understand a function's expected output.
+
+- [Function type signature structure](#function-type-signature-structure)
+  - [Parameter notation](#parameter-notation)
+- [Type variables](#type-variables)
+- [Type notation](#type-notation)
+  - [Stream types](#stream-types)
+  - [Basic types](#basic-types)
+  - [Composite types](#composite-types)
+- [Type constraints](#type-constraints)
+- [Example function type signatures](#example-function-type-signatures)
+
+## Function type signature structure
+
+```js
+(parameter: type) => output-type
+```
+
+### Parameter notation
+
+Parameter notation indicates specific behaviors of function parameters.
+
+```js
+?  // Optional parameter
+<- // Pipe receive – indicates the parameter that, by default, represents
+   // the piped-forward value
+```
+
+## Type variables
+
+Flux type signatures use **type variables** to represent unique types in the signature.
+A type variable is [polymorphic](/flux/v0.x/spec/types/#polymorphism), meaning
+it can be one of many types, and may be constrained by [type constraints](#type-constraints).
+
+Type variables use the following identifier patterns:
+
+```js
+A
+B
+C
+t11
+// etc.
+```
+
+## Type notation
+
+- [Stream types](#stream-types)
+- [Basic types](#basic-types)
+- [Composite types](#composite-types)
+
+### Stream types
+
+Type signatures identify stream types ([streams of tables](/flux/v0.x/get-started/data-model/#stream-of-tables))
+using the `stream[A]` syntax where `A` is a unique [type variable](#type-variables).
+Stream types may included specific column names and column types.
+
+```js
+// Stream of tables
+stream[A]
+
+// Stream of tables with specific columns, but inferred column types.
+stream[{col1: A, col2: B}]
+
+// Stream of tables additional or required "count" column with an
+// explicit integer type.
+stream[{A with count: int}]
+```
+
+### Basic types
+
+Type signatures identify [basic types](/flux/v0.x/data-types/basic/) with the
+following type identifiers:
+
+```js
+bool     // boolean type
+bytes    // bytes type
+duration // duration type
+float    // float type
+int      // integer type
+regexp   // regular expression type
+string   // string type
+time     // time type
+uint     // unsigned integer type
+```
+
+### Composite types
+
+Type signatures identify Flux [composite types](/flux/v0.x/data-types/composite/)
+with the following syntaxes:
+
+```js
+[A]             // array type
+[B: A]          // dictionary type
+(param: A) => B // function type
+{_value: int}   // record type
+```
+
+## Type constraints
+
+Some function parameters are "polymorphic" and can support multiple data types.
+Polymorphic parameters are bound by **type constraints**, which define what
+types can be used.
+Type signatures indicate type constraints for specific values using the
+`where A: Constraint` syntax.
+
+For example, the following type signature describes a function that takes a
+single parameter, `v` and returns and integer.
+`v` can be any type that satisfies the Timeable constraint (duration or time).
+
+```js
+(v: A) => int where A: Timeable
+```
+
+For more information about the different type constraints and the types each
+supports, see [Type constraints](/flux/v0.x/spec/types/#type-constraints).
+
+## Example function type signatures
+
+- [Function without parameters](#function-without-parameters)
+- [Function with parameters](#function-with-parameters)
+- [Pass-through transformation](#pass-through-transformation)
+- [Basic transformation](#basic-transformation)
+- [Transformation that adds a column with an explicit type](#transformation-that-adds-a-column-with-an-explicit-type)
+
+---
+
+#### Function without parameters
+
+The following type signature describes a function that:
+
+- Has no parameters
+- Returns a time value
+
+```js
+() => time
+```
+
+---
+
+#### Function with parameters
+
+The following type signature describes a function that:
+
+- Has two parameters of type `A`:
+  - multiplier _(Optional)_
+  - v ({{< req >}})
+- Returns a value the same type as the two input parameters
+
+```js
+(?multiplier: A, v: A) => A
+```
+
+---
+
+#### Pass-through transformation
+
+The following type signature describes a
+[transformation](/flux/v0.x/function-types/#transformations) that:
+
+- Takes a stream of tables of type `A` as piped-forward input
+- Returns the input stream of tables with an unmodified type
+
+```js
+(<-tables: stream[A]) => stream[A]
+```
+
+---
+
+#### Basic transformation
+
+The following type signature describes a
+[transformation](/flux/v0.x/function-types/#transformations) that:
+
+- Takes a stream of tables of type `A` as piped-forward input
+- Has an `fn` parameter with a function type
+  - `fn` uses type `A` as input and returns type `B`
+- Returns a new, modified stream of tables of type `B`
+
+```js
+(<-tables: stream[A], fn: (r: A) => B,) => stream[B]
+```
+
+---
+
+#### Transformation that adds a column with an explicit type
+The following type signature describes a
+[transformation](/flux/v0.x/function-types/#transformations) that:
+
+- Takes a stream of tables of type `A` as piped-forward input
+- Has a required **tag** parameter of type `B`
+  - The `B` type is constrained by the Stringable constraint
+- Returns a new, modified stream of tables of type `A` that includes a **tag**
+  column with string values
+
+```js
+(<-tables: stream[A], tag: B) => stream[{A with tag: string}] where B: Stringable
+```

content/flux/v0.x/stdlib/regexp/_index.md

@@ -16,7 +16,7 @@ weight: 11
 flux/v0.x/tags: [regex, functions]
 cascade:
   related:
-    - /flux/v0.x/data-types/regexp/
+    - /flux/v0.x/data-types/basic/regexp/
 introduced: 0.33.0
 ---
 

content/flux/v0.x/stdlib/regexp/findstring.md

@@ -12,7 +12,7 @@ menu:
 weight: 301
 related:
   - /flux/v0.x/stdlib/regexp/splitregexp
-  - /flux/v0.x/data-types/regexp/
+  - /flux/v0.x/data-types/basic/regexp/
 introduced: 0.33.1
 ---
 

content/flux/v0.x/stdlib/regexp/findstringindex.md

@@ -14,7 +14,7 @@ menu:
 weight: 301
 related:
   - /flux/v0.x/stdlib/regexp/compile
-  - /flux/v0.x/data-types/regexp/
+  - /flux/v0.x/data-types/basic/regexp/
 introduced: 0.33.2
 ---
 

content/flux/v0.x/stdlib/regexp/getstring.md

@@ -12,7 +12,7 @@ menu:
 weight: 301
 related:
   - /flux/v0.x/stdlib/regexp/compile
-  - /flux/v0.x/data-types/regexp/
+  - /flux/v0.x/data-types/basic/regexp/
 introduced: 0.33.3
 ---
 

content/flux/v0.x/stdlib/types/istype.md

@@ -1,9 +1,7 @@
 ---
 title: types.isType() function
 description: >
-  `types.isType()` tests if a value is a specified
-  [Flux basic type](/flux/v0.x/data-types/basic/) or
-  [regular expression type](/flux/v0.x/data-types/regexp/).
+  `types.isType()` tests if a value is a specified [Flux basic type](/flux/v0.x/data-types/basic/).
 menu:
   flux_0_x_ref:
     name: types.isType
@@ -12,9 +10,9 @@ weight: 101
 flux/v0.x/tags: [tests, types]
 ---
 
-`types.isType()` tests if a value is a specified
-[Flux basic type](/flux/v0.x/data-types/basic/) or
-[regular expression type](/flux/v0.x/data-types/regexp/). Use this function to filter your data by type. Often used to downsample or [aggregate data by type](#aggregate-or-select-data-based-on-type).
+`types.isType()` tests if a value is a specified [Flux basic type](/flux/v0.x/data-types/basic/).
+Use this function to filter your data by type. Often used to downsample or
+[aggregate data by type](#aggregate-or-select-data-based-on-type).
 
 ```js
 import "types"