From 72c3f5ea02b4c55595e2cc90f183e0a03f58be54 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ga=C3=A9tan=20Lepage?=
 <33058747+GaetanLepage@users.noreply.github.com>
Date: Thu, 30 Mar 2023 11:06:05 +0200
Subject: [PATCH] CONTRIBUTING: add documentation for mkCompositeOption (#303)

---
 CONTRIBUTING.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1fcca0df..83b89a2f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -87,6 +87,42 @@ Because the options may not have the same case (and may require some pre-process
 }
 ```
 
+#### A note on composite/nested options
+
+Here is how to handle options that have several suboptions:
+```nix
+{
+  options.my-plugin = {
+    ...
+    option1 = ...
+
+    myCompositeOption = helpers.mkCompositeOption "Description of my composite option" {
+
+      subOption1 = helpers.defaultNullOpts.mkStr "foo" "This is subOption1 which does X";
+      subOption2 = helpers.defaultNullOpts.mkStr "baz" "This is subOption2 which does Y";
+    };
+    ...
+  };
+
+  config = mkIf cfg.enabled {
+    option_1 = cfg.option1;
+    my_composite_option = with cfg.myCompositeOption;
+      helpers.ifNonNull' cfg.myCompositeOption {
+        sub_option_1 = subOption1;
+        sub_option_2 = subOption2;
+      };
+  };
+}
+```
+`mkCompositeOption` creates an option which default is `null` and which type is a `types.submodule`
+with the provided options.
+Because the default value for `myCompositeOption` is `null`, we have to handle this case in the
+implementation part using `helpers.ifNonNull'` which is defined as:
+```nix
+ifNonNull' = x: y: if x == null then null else y;
+```
+
+
 ### Tests
 
 Most of the tests of nixvim consist of creating a neovim derivation with the supplied nixvim configuration, and then try to execute neovim to check for any output. All output is considered to be an error.