From 1ac13fd4f03d2cd4c7e546c965e15be4d976a4e0 Mon Sep 17 00:00:00 2001
From: Rafael Schouten <rafaelschouten@gmail.com>
Date: Sun, 15 Sep 2024 11:49:02 +0200
Subject: [PATCH] More `@d` macro documentation (#801)

* edit broadcast docs for d macro

* add d macro keywords to docs
---
 docs/src/.vitepress/config.mts |  2 +-
 docs/src/broadcast_dims.md     | 54 ----------------------
 docs/src/broadcasts.md         | 83 ++++++++++++++++++++++++++++++++++
 3 files changed, 84 insertions(+), 55 deletions(-)
 delete mode 100644 docs/src/broadcast_dims.md
 create mode 100644 docs/src/broadcasts.md

diff --git a/docs/src/.vitepress/config.mts b/docs/src/.vitepress/config.mts
index 922cad847..05181838c 100644
--- a/docs/src/.vitepress/config.mts
+++ b/docs/src/.vitepress/config.mts
@@ -72,7 +72,7 @@ export default defineConfig({
           { text: 'DimArrays', link: '/dimarrays' },
           { text: 'DimStacks', link: '/stacks' },
           { text: 'GroupBy', link: '/groupby' },
-          { text: 'Dimension-aware broadcast', link: '/broadcast_dims.md' },
+          { text: 'Dimension-aware broadcast', link: '/broadcasts.md' },
           { text: 'Getting information', link: '/get_info' },
           { text: 'Object modification', link: '/object_modification' },
         ]},
diff --git a/docs/src/broadcast_dims.md b/docs/src/broadcast_dims.md
deleted file mode 100644
index bce50cda8..000000000
--- a/docs/src/broadcast_dims.md
+++ /dev/null
@@ -1,54 +0,0 @@
-# `broadcast_dims` and `broadcast_dims!`
-
-[`broadcast_dims`](@ref) is a dimension-aware extension to Base julia `broadcast`. 
-
-Because we know the names of the dimensions there is no ambiguity in which
-one we mean to broadcast together. We can permute and reshape dims so that 
-broadcasts that would fail with a regular `Array` just work with a `DimArray`. 
-
-As an added bonus, `broadcast_dims` even works on `DimStack`s.
-
-## Example: scaling along the time dimension
-
-Define some dimensions:
-
-````@example bd
-using DimensionalData
-using Dates
-using Statistics
-````
-
-````@ansi bd
-x, y, t = X(1:100), Y(1:25), Ti(DateTime(2000):Month(1):DateTime(2000, 12))
-````
-
-A DimArray from 1:12 to scale with:
-
-````@ansi bd
-month_scalars = DimArray(month, t)
-````
-
-And a larger DimArray for example data:
-
-````@ansi bd
-data = rand(x, y, t)
-````
-
-A regular broadcast fails:
-
-````@ansi bd
-scaled = data .* month_scalars
-````
-
-But `broadcast_dims` knows to broadcast over the `Ti` dimension:
-
-````@ansi bd
-scaled = broadcast_dims(*, data, month_scalars)
-````
-
-We can see the means of each month are scaled by the broadcast :
-
-````@ansi bd
-mean(eachslice(data; dims=(X, Y)))
-mean(eachslice(scaled; dims=(X, Y)))
-````
diff --git a/docs/src/broadcasts.md b/docs/src/broadcasts.md
new file mode 100644
index 000000000..897cae49d
--- /dev/null
+++ b/docs/src/broadcasts.md
@@ -0,0 +1,83 @@
+# Dimensional broadcasts with `@d` and `broadcast_dims`
+
+Broadcasting over AbstractDimArray works as usual with Base Julia broadcasts,
+except that dimensions are checked for compatibility with eachother, and that
+values match. Strict checks can be turned of globally with
+`strict_broadcast!(false)`. 
+To avoid even dimension name checks, broadcast over `parent(dimarray)`.
+
+The [`@d`](@ref) macro is a dimension-aware extension to regular dot brodcasting.
+[`broadcast_dims`](@ref) and [`broadcast_dims`](@ref) are analagous to Base
+julia `broadcast`. 
+
+Because we know the names of the dimensions, there is no ambiguity in which one
+we mean to broadcast together. This means we can permute and reshape dims so
+that broadcasts that would fail with a regular `Array` just work with a
+`DimArray`. 
+
+As an added bonus, `broadcast_dims` even works on `DimStack`s. Currently `@d` 
+does not work on `DimStack`.
+
+## Example: scaling along the time dimension
+
+Define some dimensions:
+
+````@example bd
+using DimensionalData
+using Dates
+using Statistics
+````
+
+````@ansi bd
+x, y, t = X(1:100), Y(1:25), Ti(DateTime(2000):Month(1):DateTime(2000, 12))
+````
+
+A DimArray from 1:12 to scale with:
+
+````@ansi bd
+month_scalars = DimArray(month, t)
+````
+
+And a larger DimArray for example data:
+
+````@ansi bd
+data = rand(x, y, t)
+````
+
+A regular broadcast fails:
+
+````@ansi bd
+scaled = data .* month_scalars
+````
+
+But `@d` knows to broadcast over the `Ti` dimension:
+
+````@ansi bd
+scaled = @d data .* month_scalars
+````
+
+We can see the means of each month are scaled by the broadcast :
+
+````@ansi bd
+mean(eachslice(data; dims=(X, Y)))
+mean(eachslice(scaled; dims=(X, Y)))
+````
+
+You can also use `broadcast_dims` the same way:
+
+````@ansi bd
+broadcast_dims(*, data, month_scalars)
+````
+
+And with the [`@d`](@ref) macro you can set the dimension order and other
+properties of the output array, by passing a single assignment or a `NamedTuple`
+argument to `@d` after the broadcast:
+
+````@ansi bd
+@d data .* month_scalars dims=(Ti, X, Y)
+````
+
+Or
+````@ansi bd
+@d data .* month_scalars (dims=(Ti, X, Y), name=:scaled)
+````