Expand documentation on exporting Spicy types

devel/spicy/reference.rst

@@ -602,6 +602,91 @@ optional on the Zeek-side, as they may not have been set during
 parsing. Unit variables are non-optional by default, unless declared
 as ``&optional`` in Spicy.
 
+.. _spicy_unit_export:
+
+Controlling created Zeek types
+""""""""""""""""""""""""""""""
+
+If needed the automatic unit type exporting described above can be customized. The general syntax for this is
+
+.. code-block:: spicy-evt
+
+    export SPICY_ID [with { [SIPCY_FIELD_NAME [&log], ]... }];
+    export SPICY_ID [as ZEEK_ID (with { [SIPCY_FIELD_NAME [&log], ]...) }];
+
+.. rubric:: Controlling exported fields
+
+Assume we are given a Spicy unit type ``foo::X``
+
+.. code-block:: spicy
+
+    module foo;
+
+    public type X = unit {
+        x: uint8;
+        y: uint8;
+        z: uint8;
+    };
+
+To create a Zeek type with only the field ``x`` to following ``export`` statements are equivalent:
+
+.. code-block:: spicy-evt
+
+    export foo::X with { y, z };
+    export foo::X as foo::X with { y, z };
+    export foo::X without { x };
+    export foo::X as foo::X without { x };
+
+.. rubric:: Adding Zeek ``&log`` attributes to created Zeek types
+
+Data intended to be written to Zeek log streams needs to be marked ``&log``. We
+can trigger creating of this attribute in exported types either per-field or
+for the whole ``record``.
+
+The forms
+
+.. code-block:: spicy-evt
+
+    export foo::X &log;
+    export foo::X as foo::X &log;
+
+both create a Zeek type
+
+.. code-block:: zeek
+
+    module foo;
+
+    export {
+
+      type X: record {
+        x: count &optional &log;
+        y: count &optional &log;
+        z: count &optional &log;
+      };
+
+    }
+
+To mark individual fields ``&log`` we would use the attribute on the respective fields, e.g.,
+
+.. code-block:: spicy-evt
+
+    export foo::X with { x &log, y, z };
+    export foo::X as foo::X with { x &log, y, z };
+
+.. code-block:: zeek
+
+    module foo;
+
+    export {
+
+      type X: record {
+        x: count &optional &log;
+        y: count &optional;
+        z: count &optional;
+      };
+
+    }
+
 .. _spicy_struct:
 
 Struct Types