Update docs to clarify range of numeric, integer, etc. and meanin…

…g of unixTimestamp (microsoft#2893) fix microsoft#2892 Clarify `numeric`, `integer`, `decimal`, `float` fix microsoft#2887 Clarify unixTimestamp encoding --------- Co-authored-by: Brian Terlson <[email protected]>
weshaggard · Feb 9, 2024 · 24d3ba0 · 24d3ba0
1 parent 71fa909
commit 24d3ba0
Show file tree

Hide file tree

Showing 5 changed files with 19 additions and 6 deletions.
diff --git a/.changeset/docs-update-types-descriptions-2024-1-7-21-24-55.md b/.changeset/docs-update-types-descriptions-2024-1-7-21-24-55.md
@@ -0,0 +1,3 @@
+---
+"@typespec/compiler": none
+---
diff --git a/.chronus/changes/docs-update-types-descriptions-2024-1-9-0-53-22.md b/.chronus/changes/docs-update-types-descriptions-2024-1-9-0-53-22.md
@@ -0,0 +1,6 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: internal
+packages:
+  - "@typespec/compiler"
+---
diff --git a/docs/language-basics/built-in-types.md b/docs/language-basics/built-in-types.md
@@ -13,9 +13,9 @@ Built in types are related to each other according to the rules described in [ty
 
 | Type         | Range                                                                                                        | Description                               |
 | ------------ | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
-| `numeric`    |                                                                                                              | Parent type for all numeric types         |
-| `integer`    |                                                                                                              | A whole-number                            |
-| `float`      |                                                                                                              | A binary number                           |
+| `numeric`    | [\*](#numeric-supertypes)                                                                                    | Parent type for all numeric types         |
+| `integer`    | [\*](#numeric-supertypes)                                                                                    | A whole-number                            |
+| `float`      | [\*](#numeric-supertypes)                                                                                    | A binary number                           |
 | `int64`      | `-9,223,372,036,854,775,808` to `9,223,372,036,854,775,807`                                                  | A 64-bit integer                          |
 | `int32`      | `-2,147,483,648` to `2,147,483,647`                                                                          | A 32-bit integer                          |
 | `int16`      | `-32,768` to `32,767`                                                                                        | A 16-bit integer                          |
@@ -27,9 +27,13 @@ Built in types are related to each other according to the rules described in [ty
 | `uint8`      | `0` to `255 `                                                                                                | Unsigned 8-bit integer                    |
 | `float32`    | <code> ±1.5 x 10<sup>45</sup></code> to <code>±3.4 x 10<sup>38</sup></code>                                  | A 32 bit floating point number            |
 | `float64`    | <code>±5.0 × 10<sup>−324</sup></code> to <code>±1.7 × 10<sup>308</sup></code>                                | A 64 bit floating point number            |
-| `decimal`    |                                                                                                              | A decimal number                          |
+| `decimal`    | [\*](#numeric-supertypes)                                                                                    | A decimal number                          |
 | `decimal128` | 34 decimal digits with an exponent range from `-6143` to `6144`                                              | A 128 bit decimal number                  |
 
+### Numeric supertypes
+
+`numeric`, `integer`, `float` and `decimal` are types that represent any possible number in their category. For some emit targets, `BigInt` or `BigDecimal` might be an analogous type satisfying the TypeSpec types `integer` and `decimal` respectively. For other targets where the language, serialization format, or protocol does not support an analogous type, emitters may decide on a policy for emitting the numeric supertypes. This might involve picking the closest analogous type and reporting a warning when they are encountered.
+
 ## Date and time types
 
 | Type             | Description                                                                         |

diff --git a/packages/compiler/lib/decorators.tsp b/packages/compiler/lib/decorators.tsp
@@ -437,7 +437,8 @@ enum DateTimeKnownEncoding {
   rfc7231: "rfc7231",
 
   /**
-   * Encode to integer
+   * Encode a datetime to a unix timestamp.
+   * Unix timestamps are represented as an integer number of seconds since the Unix epoch and usually encoded as an int32.
    */
   unixTimestamp: "unixTimestamp",
 }

diff --git a/packages/compiler/lib/lib.tsp b/packages/compiler/lib/lib.tsp
@@ -125,7 +125,6 @@ scalar boolean;
 /**
  * Represent a 32-bit unix timestamp datetime with 1s of granularity.
  * It measures time by the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970.
- *
  */
 @encode("unixTimestamp", int32)
 scalar unixTimestamp32 extends utcDateTime;