From e9adccd3a4819b3cdeb557b00f1d45167ed60a78 Mon Sep 17 00:00:00 2001
From: Paul Dee <itsascambutmailmeanyway@gmail.com>
Date: Sun, 12 Mar 2023 17:08:37 +0100
Subject: [PATCH] Update DefaultTTL.md (#2133)

---
 documentation/functions/domain/DefaultTTL.md   |  9 ++++++---
 .../functions/domain/NAMESERVER_TTL.md         | 18 ++++++++++++++++--
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/documentation/functions/domain/DefaultTTL.md b/documentation/functions/domain/DefaultTTL.md
index 2a1009fd2..8a82fbc71 100644
--- a/documentation/functions/domain/DefaultTTL.md
+++ b/documentation/functions/domain/DefaultTTL.md
@@ -6,8 +6,11 @@ parameter_types:
   ttl: Duration
 ---
 
-DefaultTTL sets the TTL for all records in a domain that do not explicitly set one with [TTL](../record/TTL.md). If neither `DefaultTTL` or `TTL` exist for a record,
-it will use the DNSControl global default of 300 seconds.
+DefaultTTL sets the TTL for all subsequent records following it in a domain that do not explicitly set one with [`TTL`](../record/TTL.md). If neither `DefaultTTL` or `TTL` exist for a record,
+the record will inherit the DNSControl global internal default of 300 seconds. See also [`DEFAULTS`](../global/DEFAULTS.md) to override the internal defaults.
+
+NS records are currently a special case, and do not inherit from `DefaultTTL`. See [`NAMESERVER_TTL`](../domain/NAMESERVER_TTL.md) to set a default TTL for all NS records.
+
 
 ```javascript
 D('example.com', REGISTRAR, DnsProvider('R53'),
@@ -17,5 +20,5 @@ D('example.com', REGISTRAR, DnsProvider('R53'),
 );
 ```
 
-The DefaultTTL duration is the same format as [TTL](../record/TTL.md), an integer number of seconds
+The DefaultTTL duration is the same format as [`TTL`](../record/TTL.md), an integer number of seconds
 or a string with a unit such as `'4d'`.
diff --git a/documentation/functions/domain/NAMESERVER_TTL.md b/documentation/functions/domain/NAMESERVER_TTL.md
index 803e57446..8a5059f4f 100644
--- a/documentation/functions/domain/NAMESERVER_TTL.md
+++ b/documentation/functions/domain/NAMESERVER_TTL.md
@@ -8,9 +8,9 @@ parameter_types:
   modifiers...: RecordModifier[]
 ---
 
-NAMESERVER_TTL sets the TTL on the domain apex NS RRs defined by [NAMESERVER](NAMESERVER.md).
+NAMESERVER_TTL sets the TTL on the domain apex NS RRs defined by [`NAMESERVER`](NAMESERVER.md).
 
-The value can be an integer or a string. See [TTL](../record/TTL.md) for examples.
+The value can be an integer or a string. See [`TTL`](../record/TTL.md) for examples.
 
 ```javascript
 D('example.com', REGISTRAR, DnsProvider('R53'),
@@ -18,3 +18,17 @@ D('example.com', REGISTRAR, DnsProvider('R53'),
   NAMESERVER('ns')
 );
 ```
+
+Use `NAMESERVER_TTL('3600'),` or `NAMESERVER_TTL('1h'),` for a 1h default TTL for all subsequent `NS` entries:
+```javascript
+D('example.com', REGISTRAR, DnsProvider('xyz'),
+  DefaultTTL("4h"),
+  NAMESERVER_TTL('3600'),
+  NAMESERVER('ns1.provider.com.'), //inherits NAMESERVER_TTL
+  NAMESERVER('ns2.provider.com.'), //inherits NAMESERVER_TTL
+  A('@','1.2.3.4'), // inherits DefaultTTL
+  A('foo', '2.3.4.5', TTL(600)) // overrides DefaultTTL for this record only
+);
+```
+
+To apply a default TTL to all other record types, see [`DefaultTTL`](../domain/DefaultTTL.md)
\ No newline at end of file