DOCS: Several improvements and cleanups (#2972)

Co-authored-by: Tom Limoncelli <[email protected]>
StackExchange · May 22, 2024 · f0d1319 · f0d1319
1 parent 107b585
commit f0d1319
Show file tree

Hide file tree

Showing 11 changed files with 11 additions and 15 deletions.
diff --git a/commands/types/dnscontrol.d.ts b/commands/types/dnscontrol.d.ts
@@ -1828,7 +1828,7 @@ declare function MX(name: string, priority: number, target: string, ...modifiers
  * If dnsconfig.js has zero `NAMESERVER()` commands for a domain, it will
  * use the API to remove all non-default nameservers.
  *
- * If dnsconfig.js has 1 or more `NAMESERVER()` commands for a domain, it
+ * If `dnsconfig.js` has 1 or more `NAMESERVER()` commands for a domain, it
  * will use the API to add those nameservers (unless, of course,
  * they already exist).
  *
@@ -2103,7 +2103,7 @@ declare function NAPTR(subdomain: string, order: number, preference: number, ter
  *
  * The main caveat of `NO_PURGE` is that intentionally deleting records becomes
  * more difficult. Suppose a `NO_PURGE` zone has an record such as A("ken",
- * "1.2.3.4"). Removing the record from dnsconfig.js will not delete "ken" from
+ * "1.2.3.4"). Removing the record from `dnsconfig.js` will not delete "ken" from
  * the domain. DNSControl has no way of knowing the record was deleted from the
  * file  The DNS record must be removed manually.  Users of `NO_PURGE` are prone
  * to finding themselves with an accumulation of orphaned DNS records. That's easy

diff --git a/documentation/code-tricks.md b/documentation/code-tricks.md
@@ -4,10 +4,10 @@ Problem: It is difficult to get CAA and other records exactly right.
 
 Solution: Use a "builder" to construct it for you.
 
-* [CAA Builder](language-reference/domain-modifiers/CAA_BUILDER.md)
-* [DMARC Builder](language-reference/domain-modifiers/DMARC_BUILDER.md)
+* [CAA_BUILDER](language-reference/domain-modifiers/CAA_BUILDER.md)
+* [DMARC_BUILDER](language-reference/domain-modifiers/DMARC_BUILDER.md)
 * [M365_BUILDER](language-reference/domain-modifiers/M365_BUILDER.md)
-* [SPF Optimizer](language-reference/domain-modifiers/SPF_BUILDER.md)
+* [SPF_BUILDER](language-reference/domain-modifiers/SPF_BUILDER.md)
 
 # Trailing commas
 
@@ -127,7 +127,7 @@ records.
 
 Solution 1: Use a macro.
 
-```
+```javascript
 function PARKED_R53(name) {
     D(name, REG_NAMECOM, DnsProvider(DSP_MY_PROVIDER),
        A("@", "10.2.3.4"),

diff --git a/documentation/language-reference/domain-modifiers/LOC_BUILDER_DD.md b/documentation/language-reference/domain-modifiers/LOC_BUILDER_DD.md
@@ -65,7 +65,6 @@ END);
 ```
 {% endcode %}
 
-
 Part of the series:
  * [`LOC()`](LOC.md) - build a `LOC` by supplying all 12 parameters
  * [`LOC_BUILDER_DD({})`](LOC_BUILDER_DD.md) - accepts cartesian x, y

diff --git a/documentation/language-reference/domain-modifiers/LOC_BUILDER_DMM_STR.md b/documentation/language-reference/domain-modifiers/LOC_BUILDER_DMM_STR.md
@@ -45,7 +45,6 @@ END);
 ```
 {% endcode %}
 
-
 Part of the series:
  * [`LOC()`](LOC.md) - build a `LOC` by supplying all 12 parameters
  * [`LOC_BUILDER_DD({})`](LOC_BUILDER_DD.md) - accepts cartesian x, y

diff --git a/documentation/language-reference/domain-modifiers/LOC_BUILDER_DMS_STR.md b/documentation/language-reference/domain-modifiers/LOC_BUILDER_DMS_STR.md
@@ -46,7 +46,6 @@ END);
 ```
 {% endcode %}
 
-
 Part of the series:
  * [`LOC()`](LOC.md) - build a `LOC` by supplying all 12 parameters
  * [`LOC_BUILDER_DD({})`](LOC_BUILDER_DD.md) - accepts cartesian x, y

diff --git a/documentation/language-reference/domain-modifiers/LOC_BUILDER_STR.md b/documentation/language-reference/domain-modifiers/LOC_BUILDER_STR.md
@@ -52,7 +52,6 @@ END);
 ```
 {% endcode %}
 
-
 Part of the series:
  * [`LOC()`](LOC.md) - build a `LOC` by supplying all 12 parameters
  * [`LOC_BUILDER_DD({})`](LOC_BUILDER_DD.md) - accepts cartesian x, y

diff --git a/documentation/language-reference/domain-modifiers/NAMESERVER.md b/documentation/language-reference/domain-modifiers/NAMESERVER.md
@@ -71,7 +71,7 @@ manually.
 If dnsconfig.js has zero `NAMESERVER()` commands for a domain, it will
 use the API to remove all non-default nameservers.
 
-If dnsconfig.js has 1 or more `NAMESERVER()` commands for a domain, it
+If `dnsconfig.js` has 1 or more `NAMESERVER()` commands for a domain, it
 will use the API to add those nameservers (unless, of course,
 they already exist).
 

diff --git a/documentation/language-reference/domain-modifiers/NO_PURGE.md b/documentation/language-reference/domain-modifiers/NO_PURGE.md
@@ -35,7 +35,7 @@ END);
 
 The main caveat of `NO_PURGE` is that intentionally deleting records becomes
 more difficult. Suppose a `NO_PURGE` zone has an record such as A("ken",
-"1.2.3.4"). Removing the record from dnsconfig.js will not delete "ken" from
+"1.2.3.4"). Removing the record from `dnsconfig.js` will not delete "ken" from
 the domain. DNSControl has no way of knowing the record was deleted from the
 file  The DNS record must be removed manually.  Users of `NO_PURGE` are prone
 to finding themselves with an accumulation of orphaned DNS records. That's easy

diff --git a/documentation/why-the-dot.md b/documentation/why-the-dot.md
@@ -46,7 +46,7 @@ How are they ambiguous?
 
   * Should $DOMAIN be added to "bar.com"?  Well, obviously not, because it already ends with ".com" and we all know that "bar.com.bar.com" is probably not what they want. No, it isn't that obvious!  Why?  (see the next bullet point)
   * Should $DOMAIN be added to "meta.xyz"?  Everyone knows that ".xyz" isn't a TLD. Obviously, yes, $DOMAIN should be appended. However, wait...  ".xyz" became a TLD in June 2014.  We don't want to be surprised by changes like that.  Also, users should not be required to memorize all the TLDs. (In the old days it was reasonable to expect people to memorize the 7 TLDS (gov/edu/com/mil/org/net) but since 2000 that's all changed. By the way, we forgot to include "int" in the original and you didn't notice.)
-  * What is the CNAME target is "www.bar.com" and the domain is "bar.com".  Then It is reasonable to infer the user's intent, right?  "www.bar.com.bar.com." would be silly, right?  Maybe. What if we are copying 100 lines of dnsconfig.js from one `D()` to another. Buried in the middle is this one CNAME that means something entirely different when in a new $DOMAIN. That would be bad.  We've seen this in production and want to prevent this kind of error.
+  * What if the CNAME target is "www.bar.com" and the domain is "bar.com"?  Then It is reasonable to infer the user's intent, right?  `www.bar.com.bar.com.` would be silly, right?  Maybe. What if we are copying 100 lines of `dnsconfig.js` from one `D()` to another. Buried in the middle is this one CNAME that means something entirely different when in a new $DOMAIN. That would be bad.  We've seen this in production and want to prevent this kind of error.
 
 Yes, we could layer rule upon rule upon rule.  Eventually we'd get
 all the rules right.  However, now a user would have to know all the

diff --git a/integrationTest/integration_test.go b/integrationTest/integration_test.go
@@ -812,7 +812,7 @@ func makeTests() []*TestGroup {
 
 	// clear() is the same as tc("Empty").  It removes all records.
 	// Each testgroup() begins with clear() automagically. You do not
-	// have to include the clear() in teach testgroup().
+	// have to include the clear() in each testgroup().
 
 	tests := []*TestGroup{
 

diff --git a/providers/capabilities.go b/providers/capabilities.go
@@ -90,7 +90,7 @@ const (
 	// DocCreateDomains means provider can add domains with the `dnscontrol create-domains` command
 	DocCreateDomains
 
-	// DocDualHost means provider allows full management of apex NS records, so we can safely dual-host with anothe provider
+	// DocDualHost means provider allows full management of apex NS records, so we can safely dual-host with another provider
 	DocDualHost
 
 	// DocOfficiallySupported means it is actively used and maintained by stack exchange