JSON documentation: reformat

Author: schweikert

CHANGELOG.md

@@ -3,8 +3,10 @@ Next
 
 ## New features
 
-- New option -J / --json for the JSON output (#386, thanks @bonkf,
-  @JoshIPT, @sebast-gsnw and @auerswal)
+- New option -J / --json for JSON output. See doc/fping-json.md for
+  the JSON schema. This feature is still in alpha and the schema
+  might change in future releases (#386, thanks @bonkf,
+  @JoshIPT, @sebast-gsnw, and @auerswal).
 - The -g, --generate option now also supports IPv6 addresses (#376,
   thanks @auerswal)
 - New option --seqmap-timeout to control the time after which sequence

doc/fping-json.md

@@ -1,10 +1,13 @@
 # fping JSON Output Format
+
 last updated for: fping 5.5
 
-> [!IMPORTANT]
-> The JSON output feature is currently in **alpha**. The format is subject to change in future versions.
+> [!IMPORTANT] The JSON output feature is currently in **alpha**. The format is
+> subject to change in future versions.
 
-When using the `--json` (or `-J`) option, fping outputs results as a **stream of JSON objects**, separated by newlines. Each line in the output is a valid, independent JSON document representing a specific event or statistic.
+When using the `--json` (or `-J`) option, fping outputs results as a **stream of
+JSON objects**, separated by newlines. Each line in the output is a valid,
+independent JSON document representing a specific event or statistic.
 
 ## General Format
 
@@ -14,11 +17,14 @@ Every JSON object output by fping follows the following pattern:
 { "type": { "field1": "value1", "field2": "value2" } }
 ```
 
-Where `type` identifies the type of the object (e.g., `resp`, `summary`) and the inner object contains the fields relevant to that type.
+Where `type` identifies the type of the object (e.g., `resp`, `summary`) and the
+inner object contains the fields relevant to that type.
 
 ## Forward Compatibility
 
-Any unknown object types and any unknown fields should be ignored for forward-compatibility (we might add new objects and fields to objects over time).
+Any unknown object types and any unknown fields should be ignored for
+forward-compatibility (we might add new objects and fields to objects over
+time).
 
 ## Example
 
@@ -34,17 +40,19 @@ $ fping -J -c3 8.8.8.8
 
 ## JSON Object Types
 
-> [!NOTE]
-> In the actual output, each JSON object is compacted onto a single line. The examples in this document are formatted across multiple lines for readability.
+> [!NOTE] In the actual output, each JSON object is compacted onto a single
+> line. The examples in this document are formatted across multiple lines for
+> readability.
 
-The following top-level keys identify the type of information contained in each JSON object:
+The following top-level keys identify the type of information contained in each
+JSON object:
 
-*   `resp`: Response to a ping packet.
-*   `timeout`: Timeout waiting for a packet response.
-*   `summary`: Summary statistics for a host (used with `-c`).
-*   `vSum`: Summary of all RTT values for a host (used with `-C`).
-*   `globalSum`: Global statistics for the entire run (used with `-s`).
-*   `intSum`: Interval summary statistics (used with `-Q`).
+- `resp`: Response to a ping packet.
+- `timeout`: Timeout waiting for a packet response.
+- `summary`: Summary statistics for a host (used with `-c`).
+- `vSum`: Summary of all RTT values for a host (used with `-C`).
+- `globalSum`: Global statistics for the entire run (used with `-s`).
+- `intSum`: Interval summary statistics (used with `-Q`).
 
 ### `resp`: Response
 
@@ -61,16 +69,17 @@ Generated when a ping reply is received.
 }
 ```
 
-*   `host`: Target hostname or IP.
-*   `seq`: Sequence number of the packet (0-indexed).
-*   `size`: Size of the received packet in bytes.
-*   `rtt`: Round-trip time in milliseconds.
+- `host`: Target hostname or IP.
+- `seq`: Sequence number of the packet (0-indexed).
+- `size`: Size of the received packet in bytes.
+- `rtt`: Round-trip time in milliseconds.
 
 **Optional Fields:**
 
-*   `timestamps`: If ICMP timestamp requests are used (`--icmp-timestamp`), contains `originate`, `receive`, `transmit`, and `localreceive` timestamps.
-*   `tos`: If `--print-tos` is used, contains the Type of Service value.
-*   `ttl`: If `--print-ttl` is used, contains the Time To Live value.
+- `timestamps`: If ICMP timestamp requests are used (`--icmp-timestamp`),
+  contains `originate`, `receive`, `transmit`, and `localreceive` timestamps.
+- `tos`: If `--print-tos` is used, contains the Type of Service value.
+- `ttl`: If `--print-ttl` is used, contains the Time To Live value.
 
 ### `timeout`: Timeout
 
@@ -85,8 +94,8 @@ Generated when a packet times out.
 }
 ```
 
-*   `host`: Target hostname or IP.
-*   `seq`: Sequence number of the timed-out packet.
+- `host`: Target hostname or IP.
+- `seq`: Sequence number of the timed-out packet.
 
 ### `summary`: Host Summary
 
@@ -107,31 +116,28 @@ Generated at end of execution (or interval) when using `-c` (count mode).
 }
 ```
 
-*   `xmt`: Packets transmitted.
-*   `rcv`: Packets received.
-*   `loss`: Packet loss percentage.
-*   `outage(ms)`: Total outage time in milliseconds (only if `--outage` is used).
-*   `rttMin`, `rttAvg`, `rttMax`: Minimum, average, and maximum RTTs.
+- `xmt`: Packets transmitted.
+- `rcv`: Packets received.
+- `loss`: Packet loss percentage.
+- `outage(ms)`: Total outage time in milliseconds (only if `--outage` is used).
+- `rttMin`, `rttAvg`, `rttMax`: Minimum, average, and maximum RTTs.
 
 ### `vSum`: Full RTT Summary
 
-Generated at end of execution when using `-C` (count mode with per-packet RTT reporting).
+Generated at end of execution when using `-C` (count mode with per-packet RTT
+reporting).
 
 ```json
 {
   "vSum": {
     "host": "127.0.0.1",
-    "values": [
-      0.054,
-      0.062,
-      null,
-      0.081
-    ]
+    "values": [0.054, 0.062, null, 0.081]
   }
 }
 ```
 
-*   `values`: Array of RTT values (in ms) for each sequence number. `null` indicates a timeout/loss.
+- `values`: Array of RTT values (in ms) for each sequence number. `null`
+  indicates a timeout/loss.
 
 ### `intSum`: Interval Summary
 
@@ -152,8 +158,8 @@ Generated periodically when using `-Q` (quiet with interval reporting).
 }
 ```
 
-*   `time`: Unix timestamp of the report.
-*   Other fields are similar to `summary`.
+- `time`: Unix timestamp of the report.
+- Other fields are similar to `summary`.
 
 ### `globalSum`: Global Summary