doc: add missing definitions to internal-api.md

avivkeller · marco-ippolito · commit 9947fc112f39 · 2024-11-17T11:51:29.000+01:00
PR-URL: #53303 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
diff --git a/doc/contributing/internal-api.md b/doc/contributing/internal-api.md
@@ -1,33 +1,41 @@
-These flags are for Node.js core development usage only. Do not use these flags
-in your own applications. These flags are not subjected to semantic versioning
-rules. The core developers may remove these flags in any version of Node.js.
+# Node.js Core Development Flags
 
-# Internal documentation of Node.js
+These flags are specifically designed for use in Node.js core development and are not intended for general
+application usage.
 
-## CLI
+> \[!NOTE]
+> These APIs are not bound by semantic versioning rules, and they can be altered or removed in any version of Node.js
+
+## Command Line Interface (CLI)
 
 ### Flags
 
 #### `--debug-arraybuffer-allocations`
 
+Enables debugging of `ArrayBuffer` allocations.
+
 #### `--expose-internals`
 
-Allows to require the `internal/*` modules.
+Allows the usage of `internal/*` modules, granting access to internal Node.js functionality.
 
 #### `--inspect-brk-node[=[host:]port]`
 
-<!-- YAML
-added: v7.6.0
--->
-
-Activate inspector on `host:port` and break at start of the first internal
-JavaScript script executed when the inspector is available.
-Default `host:port` is `127.0.0.1:9229`.
+Pauses execution at the start of Node.js application code, waiting for a debugger to connect on the specified
+`host` and `port`. This is useful for debugging application startup issues. If `host` and `port` are not
+provided, it defaults to `127.0.0.1:9229`.
 
 #### `--node-snapshot`
 
+Enables the use of Node.js snapshots, potentially improving startup performance.
+
 #### `--test-udp-no-try-send`
 
+Used for testing UDP functionality without attempting to send data.
+
 #### `--trace-promises`
 
+Enables tracing of promises for debugging and performance analysis.
+
 #### `--verify-base-objects`
+
+Allows verification of base objects for debugging purposes.
