Improve docs for data types comparison table

whatyouhide · Sep 1, 2023 · 5854af0 · 5854af0
1 parent 67e9cf1
commit 5854af0
Show file tree

Hide file tree

Showing 2 changed files with 77 additions and 19 deletions.
diff --git a/pages/Data types comparison table.md b/pages/Data types comparison table.md
@@ -1,23 +1,37 @@
-# Data types comparison table
+# Data Types Comparison Table
 
 This page contains a table that compares the data types used by Cassandra with their counterparts used by Xandra. Each Cassandra data type corresponds to one or more Elixir data types. What Elixir data type is used for a given Cassandra type is often controlled by a formatting option. For example, a `date` value from Cassandra can be returned as a `Date.t()` struct or as an integer representing the number of days since the Unix epoch depending on the `:date_format` option passed to various Xandra functions.
 
-## Comparison table
+## Comparison Table
 
-| Cassandra data type                                         | Elixir data type                                           |
-|-------------------------------------------------------------|------------------------------------------------------------|
-| `NULL`                                                      | `nil`                                                      |
-| `bool`                                                      | `boolean()`                                                |
-| `float`, `double`                                           | `float()`                                                  |
-| `int`, `bigint`, `smallint`, `varint`, `tinyint`, `counter` | `integer()`                                                |
-| `decimal`                                                   | `Decimal.t()`, `{value, scale}`                            |
-| `ascii`, `varchar`, `text`                                  | `String.t()`                                               |
-| `blob`                                                      | `binary()`                                                 |
-| `date`                                                      | `Date.t()`, `integer()` (days from Unix epoch)             |
-| `timestamp`                                                 | `DateTime.t()`, `integer()` (milliseconds from Unix epoch) |
-| `time`                                                      | `Time.t()`, `integer()` (nanoseconds from midnight)        |
-| `list`                                                      | `list()`                                                   |
-| `tuple`                                                     | `tuple()`                                                  |
-| `set`                                                       | `MapSet.t()`                                               |
-| `map`                                                       | `map()`                                                    |
-| `uuid`, `timeuuid`                                          | `binary()`                                                 |
+| Cassandra data type | Elixir data type                                                                 |
+| ------------------- | -------------------------------------------------------------------------------- |
+| `ascii`             | `t:String.t/0`                                                                   |
+| `bigint`            | `t:integer/0`                                                                    |
+| `blob`              | `t:binary/0`                                                                     |
+| `boolean`           | `t:boolean/0`                                                                    |
+| `counter`           | `t:integer/0`                                                                    |
+| `date`              | `t:Date.t/0` (if `date_format: :date`)                                           |
+| `date`              | `t:integer/0` (if `date_format: :integer`), days from Unix epoch                 |
+| `decimal`           | `{value, scale}` (if `decimal_format: :tuple`), where `value * 10^(-1 * scale)`  |
+| `decimal`           | `t:Decimal.t/0` (if `decimal_format: :decimal`)                                  |
+| `double`            | `t:float/0`                                                                      |
+| `float`             | `t:float/0`                                                                      |
+| `inet`              | `t::inet.ip_address/0`                                                           |
+| `int`               | `t:integer/0`                                                                    |
+| `list<T>`           | `t:list/0`                                                                       |
+| `map<KeyT, ValueT>` | `t:map/0`                                                                        |
+| `NULL`              | `nil`                                                                            |
+| `set<T>`            | `t:MapSet.t/0`                                                                   |
+| `smallint`          | `t:integer/0`                                                                    |
+| `text`              | `t:String.t/0`                                                                   |
+| `time`              | `t:integer/0` (if `time_format: :integer`), as nanoseconds from midnight         |
+| `time`              | `t:Time.t/0` (if `time_format: :time`)                                           |
+| `timestamp`         | `t:DateTime.t/0` (if `timestamp_format: :datetime`)                              |
+| `timestamp`         | `t:integer/0` (if `timestamp_format: :integer`), as milliseconds from Unix epoch |
+| `timeuuid`          | `t:binary/0`                                                                     |
+| `tinyint`           | `t:integer/0`                                                                    |
+| `tuple<...>`        | `t:tuple/0`                                                                      |
+| `uuid`              | `t:binary/0`                                                                     |
+| `varchar`           | `t:String.t/0`                                                                   |
+| `varint`            | `t:integer/0`                                                                    |
diff --git a/test/integration/datatypes_test.exs b/test/integration/datatypes_test.exs
@@ -1,6 +1,50 @@
 defmodule DataTypesTest do
   use XandraTest.IntegrationCase, async: true
 
+  @types_that_should_be_documented MapSet.new([
+                                     :ascii,
+                                     :bigint,
+                                     :blob,
+                                     :boolean,
+                                     :counter,
+                                     :date,
+                                     :decimal,
+                                     :double,
+                                     :float,
+                                     :inet,
+                                     :int,
+                                     :smallint,
+                                     :text,
+                                     :time,
+                                     :timestamp,
+                                     :timeuuid,
+                                     :tinyint,
+                                     :uuid,
+                                     :varchar,
+                                     :varint,
+                                     :map,
+                                     :set,
+                                     :list,
+                                     :tuple
+                                   ])
+
+  test "all the datatypes are documented in the guides" do
+    types_in_guides =
+      Mix.Project.project_file()
+      |> Path.dirname()
+      |> Path.join("pages/Data types comparison table.md")
+      |> File.read!()
+      |> String.split("\n")
+      |> Enum.filter(&String.starts_with?(&1, "| `"))
+      |> MapSet.new(fn "| `" <> line ->
+        [type, _rest] = String.split(line, ["`", "<"], parts: 2)
+        String.to_atom(type)
+      end)
+      |> MapSet.delete(:NULL)
+
+    assert types_in_guides == @types_that_should_be_documented
+  end
+
   test "primitive datatypes", %{conn: conn} do
     statement = """
     CREATE TABLE primitives