Pull request 2326: more-md-lint

Merge in DNS/adguard-home from more-md-lint to master Squashed commit of the following: commit 39e7ea3 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Thu Dec 19 17:03:36 2024 +0300 all: imp docs more commit 7aa0803 Author: Ainar Garipov <A.Garipov@AdGuard.COM> Date: Thu Dec 19 16:08:13 2024 +0300 all: add more docs to lint
AdguardTeam · Dec 19, 2024 · 20e56b7 · 20e56b7
1 parent 261c159
commit 20e56b7
Show file tree

Hide file tree

Showing 8 changed files with 231 additions and 399 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/internal/dhcpd/README.md b/internal/dhcpd/README.md
@@ -1,96 +1,84 @@
- #  Testing DHCP Server
+# Testing DHCP Server
 
 Contents:
- *  [Test setup with Virtual Box](#vbox)
- *  [Quick test with DHCPTest](#dhcptest)
 
-##  <a href="#vbox" id="vbox" name="vbox">Test setup with Virtual Box</a>
+- [Test setup with Virtual Box](#vbox)
+- [Quick test with DHCPTest](#dhcptest)
 
-   ### Prerequisites
+## <a href="#vbox" id="vbox" name="vbox">Test setup with Virtual Box</a>
 
-To set up a test environment for DHCP server you will need:
-
- *  Linux AG Home host machine (Virtual).
- *  Virtual Box.
- *  Virtual machine (guest OS doesn't matter).
+### Prerequisites
 
-   ### Configure Virtual Box
+To set up a test environment for DHCP server you will need:
 
- 1.  Install Virtual Box and run the following command to create a Host-Only
-     network:
+- Linux AG Home host machine (Virtual)
+- Virtual Box
+- Virtual machine (guest OS doesn't matter)
 
-     ```sh
-     $ VBoxManage hostonlyif create
-     ```
+### Configure Virtual Box
 
-     You can check its status by `ip a` command.
+1. Install Virtual Box and run the following command to create a Host-Only network:
 
-     You can also set up Host-Only network using Virtual Box menu:
+    ```sh
+    VBoxManage hostonlyif create
+    ```
 
-     ```
-     File -> Host Network Manager...
-     ```
+    You can check its status by `ip a` command.
 
- 2.  Create your virtual machine and set up its network:
+    You can also set up Host-Only network using Virtual Box menu in *File → Host Network Manager.*
 
-     ```
-     VM Settings -> Network -> Host-only Adapter
-     ```
+2. Create your virtual machine and set up its network in *VM Settings → Network → Host-only Adapter.*
 
- 3.  Start your VM, install an OS.  Configure your network interface to use
-     DHCP and the OS should ask for a IP address from our DHCP server.
+3. Start your VM, install an OS. Configure your network interface to use DHCP and the OS should ask for a IP address from our DHCP server.
 
- 4.  To see the current IP addresses on client OS you can use `ip a` command on
-     Linux or `ipconfig` on Windows.
+4. To see the current IP addresses on client OS you can use `ip a` command on Linux or `ipconfig` on Windows.
 
- 5.  To force the client OS to request an IP from DHCP server again, you can
-     use `dhclient` on Linux or `ipconfig /release` on Windows.
+5. To force the client OS to request an IP from DHCP server again, you can use `dhclient` on Linux or `ipconfig /release` on Windows.
 
-   ### Configure server
+### Configure server
 
- 1.  Edit server configuration file `AdGuardHome.yaml`, for example:
+1. Edit server configuration file `AdGuardHome.yaml`, for example:
 
-     ```yaml
-     dhcp:
-          enabled: true
-          interface_name: vboxnet0
-          local_domain_name: lan
-          dhcpv4:
+    ```yaml
+    dhcp:
+        enabled: true
+        interface_name: vboxnet0
+        local_domain_name: lan
+        dhcpv4:
             gateway_ip: 192.168.56.1
             subnet_mask: 255.255.255.0
             range_start: 192.168.56.2
             range_end: 192.168.56.2
             lease_duration: 86400
             icmp_timeout_msec: 1000
             options: []
-          dhcpv6:
+        dhcpv6:
             range_start: 2001::1
             lease_duration: 86400
             ra_slaac_only: false
             ra_allow_slaac: false
-     ```
+    ```
 
- 2.  Start the server
+2. Start the server:
 
-     ```sh
-     ./AdGuardHome -v
-     ```
+    ```sh
+    ./AdGuardHome -v
+    ```
 
-     There should be a message in log which shows that DHCP server is ready:
+    There should be a message in log which shows that DHCP server is ready:
 
-     ```
-     [info] DHCP: listening on 0.0.0.0:67
-     ```
+    ```none
+    [info] dhcpv4: listening
+    ```
 
-##  <a href="#dhcptest" id="dhcptest" name="dhcptest">Quick test with DHCPTest utility</a>
+## <a href="#dhcptest" id="dhcptest" name="dhcptest">Quick test with DHCPTest utility</a>
 
-   ### Prerequisites
+### Prerequisites
 
- *  [DHCP test utility][dhcptest-gh].
+- [DHCP test utility][dhcptest-gh].
 
-   ### Quick test
+### Quick test
 
-The DHCP server could be tested for DISCOVER-OFFER packets with in
-interactive mode.
+The DHCP server could be tested for DISCOVER-OFFER packets with in interactive mode.
 
 [dhcptest-gh]: https://github.com/CyberShadow/dhcptest
diff --git a/internal/filtering/README.md b/internal/filtering/README.md
diff --git a/internal/next/changelog.md b/internal/next/changelog.md
@@ -1,15 +1,17 @@
 # AdGuard Home v0.108.0 Changelog DRAFT
 
-This changelog should be merged into the main one once the next API matures
-enough.
+This changelog should be merged into the main one once the next API matures enough.
 
 ## [v0.108.0] - TODO
 
 ### Added
 
 - The ability to change the port of the pprof debug API.
+
 - The ability to log to stderr using `--logFile=stderr`.
+
 - The new `--web-addr` flag to set the Web UI address in a `host:port` form.
+
 - `SIGHUP` now reloads all configuration from the configuration file ([#5676]).
 
 ### Changed
@@ -20,20 +22,21 @@ enough.
 
 #### Other changes
 
-- `-h` is now an alias for `--help` instead of the removed `--host`, see below.
-  Use `--web-addr=host:port` to set an address on which to serve the Web UI.
+- `-h` is now an alias for `--help` instead of the removed `--host`, see below. Use `--web-addr=host:port` to set an address on which to serve the Web UI.
 
 ### Fixed
 
 - `--check-config` breaking the configuration file ([#4067]).
+
 - Inconsistent application of `--work-dir/-w` ([#2598], [#2902]).
+
 - The order of `-v/--verbose` and `--version` being significant ([#2893]).
 
 ### Removed
 
 - The deprecated `--no-mem-optimization` and `--no-etc-hosts` flags.
-- `--host` and `-p/--port` flags.  Use `--web-addr=host:port` to set an address
-  on which to serve the Web UI.  `-h` is now an alias for `--help`, see above.
+
+- `--host` and `-p/--port` flags.  Use `--web-addr=host:port` to set an address on which to serve the Web UI.  `-h` is now an alias for `--help`, see above.
 
 [#2598]: https://github.com/AdguardTeam/AdGuardHome/issues/2598
 [#2893]: https://github.com/AdguardTeam/AdGuardHome/issues/2893

diff --git a/openapi/CHANGELOG.md b/openapi/CHANGELOG.md
@@ -55,9 +55,9 @@
 
 ### The new fields `"upstreams_cache_enabled"` and `"upstreams_cache_size"` in `Client` object
 
-- The new field `"upstreams_cache_enabled"` in `GET /control/clients`, `GET /control/clients/find`, `POST /control/clients/add`, and `POST /control/clients/update` methods shows if client's DNS cache is enabled for the client.  If not set AdGuard Home will use default value (false).
+- The new field `"upstreams_cache_enabled"` in `GET /control/clients`, `GET /control/clients/find`, `POST /control/clients/add`, and `POST /control/clients/update` methods shows if client’s DNS cache is enabled for the client.  If not set AdGuard Home will use default value (false).
 
-- The new field `"upstreams_cache_size"` in `GET /control/clients`, `GET /control/clients/find`, `POST /control/clients/add`, and `POST /control/clients/update` methods is the size of client's DNS cache in bytes.
+- The new field `"upstreams_cache_size"` in `GET /control/clients`, `GET /control/clients/find`, `POST /control/clients/add`, and `POST /control/clients/update` methods is the size of client’s DNS cache in bytes.
 
 ### The new field `"ratelimit_subnet_len_ipv4"` in `DNSConfig` object
 
@@ -218,7 +218,7 @@ The new field `blocked_services_schedule` has been added to JSON objects.  It ha
 
 - The `GET /control/stats_info` HTTP API; use the new `GET /control/stats/config` API instead.
 
-    **NOTE:** If `interval` was configured by editing configuration file or new HTTP API call `PUT /control/stats/config/update` and it's not equal to previous allowed enum values then it will be equal to `90` days for compatibility reasons.
+    **NOTE:** If `interval` was configured by editing configuration file or new HTTP API call `PUT /control/stats/config/update` and it’s not equal to previous allowed enum values then it will be equal to `90` days for compatibility reasons.
 
 - The `POST /control/stats_config` HTTP API; use the new `PUT /control/stats/config/update` API instead.
 
@@ -244,7 +244,7 @@ These `control/stats/config/update` and `control/stats/config` APIs accept and r
 
 - The `GET /control/querylog_info` HTTP API; use the new `GET /control/querylog/config` API instead.
 
-    **NOTE:** If `interval` was configured by editing configuration file or new HTTP API call `PUT /control/querylog/config/update` and it's not equal to previous allowed enum values then it will be equal to `90` days for compatibility reasons.
+    **NOTE:** If `interval` was configured by editing configuration file or new HTTP API call `PUT /control/querylog/config/update` and it’s not equal to previous allowed enum values then it will be equal to `90` days for compatibility reasons.
 
 - The `POST /control/querylog_config` HTTP API; use the new `PUT /control/querylog/config/update` API instead.
 
@@ -501,7 +501,7 @@ Previously, the API accepted the name of the network interface as a plain-text s
 
 - Value of `-1` is now used for rules generated from the operating system hosts files.
 
-- Value of `-2` is now used for blocked services' rules.
+- Value of `-2` is now used for blocked services’ rules.
 
 - Value of `-3` is now used for rules generated by parental control web service.
 
@@ -511,7 +511,7 @@ Previously, the API accepted the name of the network interface as a plain-text s
 
 ### New possible value of `"name"` field in `QueryLogItemClient`
 
-- The value of `"name"` field in `GET /control/querylog` method is never empty, either persistent client's name or runtime client's hostname.
+- The value of `"name"` field in `GET /control/querylog` method is never empty, either persistent client’s name or runtime client’s hostname.
 
 ### Lists in `AccessList`
 
@@ -531,7 +531,7 @@ Previously, the API accepted the name of the network interface as a plain-text s
 
 ### New possible value of `"interval"` field in `QueryLogConfig`
 
-- The value of `"interval"` field in `POST /control/querylog_config` and `GET /control/querylog_info` methods could now take the value of `0.25`.  It's equal to 6 hours.
+- The value of `"interval"` field in `POST /control/querylog_config` and `GET /control/querylog_info` methods could now take the value of `0.25`.  It’s equal to 6 hours.
 
 - All the possible values of `"interval"` field are enumerated.
 
@@ -543,7 +543,7 @@ Previously, the API accepted the name of the network interface as a plain-text s
 
 ### The new field `"unicode_name"` in `DNSQuestion`
 
-- The new optional field `"unicode_name"` is the Unicode representation of question's domain name.  It is only presented if the original question's domain name is an IDN.
+- The new optional field `"unicode_name"` is the Unicode representation of question’s domain name.  It is only presented if the original question’s domain name is an IDN.
 
 ### Documentation fix of `DNSQuestion`
 
@@ -555,11 +555,11 @@ Previously, the API accepted the name of the network interface as a plain-text s
 
 ### `POST /control/dhcp/reset_leases`
 
-- The new `POST /control/dhcp/reset_leases` HTTP API allows removing all leases from the DHCP server's database without erasing its configuration.
+- The new `POST /control/dhcp/reset_leases` HTTP API allows removing all leases from the DHCP server’s database without erasing its configuration.
 
 ### The parameter `"host"` in `GET /apple/*.mobileconfig` is now required
 
-- The parameter `"host"` in `GET` requests for `/apple/doh.mobileconfig` and `/apple/doh.mobileconfig` is now required to prevent unexpected server name's value.
+- The parameter `"host"` in `GET` requests for `/apple/doh.mobileconfig` and `/apple/doh.mobileconfig` is now required to prevent unexpected server name’s value.
 
 ### The new field `"default_local_ptr_upstreams"` in `GET /control/dns_info`
 
@@ -589,7 +589,7 @@ Previously, the API accepted the name of the network interface as a plain-text s
 
 ### New fields `"resolve_clients"` and `"local_ptr_upstreams"` in DNS configuration
 
-- The new optional field `"resolve_clients"` of `DNSConfig` is used to turn resolving clients' addresses on and off.
+- The new optional field `"resolve_clients"` of `DNSConfig` is used to turn resolving clients’ addresses on and off.
 
 - The new optional field `"local_ptr_upstreams"` of `"DNSConfig"` contains the upstream servers for resolving addresses from locally-served networks.  The empty `"local_ptr_resolvers"` states that AGH should use resolvers provided by the operating system.
 
@@ -615,7 +615,7 @@ Previously, the API accepted the name of the network interface as a plain-text s
 
 ### Multiple matched rules in `GET /filtering/check_host` and `GET /querylog`
 
-- The properties `rule` and `filter_id` are now deprecated.  API users should inspect the newly-added `rules` object array instead.  For most rules, it's either empty or contains one object, which contains the same things as the old two properties did, but under more correct names:
+- The properties `rule` and `filter_id` are now deprecated.  API users should inspect the newly-added `rules` object array instead.  For most rules, it’s either empty or contains one object, which contains the same things as the old two properties did, but under more correct names:
 
     ```js
     {
@@ -678,7 +678,7 @@ Previously, the API accepted the name of the network interface as a plain-text s
 
 - Added optional "offset" and "limit" parameters.
 
-  We are still using "older_than" approach in AdGuard Home UI, but we realize that it's easier to use offset/limit so here is this option now.
+  We are still using "older_than" approach in AdGuard Home UI, but we realize that it’s easier to use offset/limit so here is this option now.
 
 ## v0.102: API changes
 
@@ -914,9 +914,9 @@ Replaces the `POST /control/enable_protection` and `POST /control/disable_protec
 
 ### A note about web user authentication
 
-If AdGuard Home's web user is password-protected, a web client must use authentication mechanism when sending requests to server.  Basic access authentication is the most simple method - a client must pass `Authorization` HTTP header along with all requests:
+If AdGuard Home’s web user is password-protected, a web client must use authentication mechanism when sending requests to server.  Basic access authentication is the most simple method - a client must pass `Authorization` HTTP header along with all requests:
 
-  ```none
+  ```http
   Authorization: Basic BASE64_DATA
   ```