doc: add dynamic source code links

Fixes: https://github.com/nodejs/node/pull/33977

PR-URL: https://github.com/nodejs/node/pull/33996
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

doc/api/assert.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/assert.js -->
+
 The `assert` module provides a set of assertion functions for verifying
 invariants.
 

doc/api/async_hooks.md

@@ -4,6 +4,8 @@
 
 > Stability: 1 - Experimental
 
+<!-- source_link=lib/async_hooks.js -->
+
 The `async_hooks` module provides an API to track asynchronous resources. It
 can be accessed using:
 

doc/api/buffer.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/buffer.js -->
+
 In Node.js, `Buffer` objects are used to represent binary data in the form
 of a sequence of bytes. Many Node.js APIs, for example streams and file system
 operations, support `Buffer`s, as interactions with the operating system or

doc/api/child_process.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/child_process.js -->
+
 The `child_process` module provides the ability to spawn child processes in
 a manner that is similar, but not identical, to popen(3). This capability
 is primarily provided by the [`child_process.spawn()`][] function:

doc/api/cluster.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/cluster.js -->
+
 A single instance of Node.js runs in a single thread. To take advantage of
 multi-core systems, the user will sometimes want to launch a cluster of Node.js
 processes to handle the load.

doc/api/console.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/console.js -->
+
 The `console` module provides a simple debugging console that is similar to the
 JavaScript console mechanism provided by web browsers.
 

doc/api/crypto.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/crypto.js -->
+
 The `crypto` module provides cryptographic functionality that includes a set of
 wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign, and verify functions.
 

doc/api/dgram.md

@@ -6,6 +6,8 @@
 
 <!-- name=dgram -->
 
+<!-- source_link=lib/dgram.js -->
+
 The `dgram` module provides an implementation of UDP datagram sockets.
 
 ```js

doc/api/dns.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/dns.js -->
+
 The `dns` module enables name resolution. For example, use it to look up IP
 addresses of host names.
 

doc/api/domain.md

@@ -16,6 +16,8 @@ changes:
 
 > Stability: 0 - Deprecated
 
+<!-- source_link=lib/domain.js -->
+
 **This module is pending deprecation**. Once a replacement API has been
 finalized, this module will be fully deprecated. Most end users should
 **not** have cause to use this module. Users who absolutely must have

doc/api/events.md

@@ -6,6 +6,8 @@
 
 <!--type=module-->
 
+<!-- source_link=lib/events.js -->
+
 Much of the Node.js core API is built around an idiomatic asynchronous
 event-driven architecture in which certain kinds of objects (called "emitters")
 emit named events that cause `Function` objects ("listeners") to be called.

doc/api/fs.md

@@ -6,6 +6,8 @@
 
 <!--name=fs-->
 
+<!-- source_link=lib/fs.js -->
+
 The `fs` module provides an API for interacting with the file system in a
 manner closely modeled around standard POSIX functions.
 

doc/api/http.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/http.js -->
+
 To use the HTTP server and client one must `require('http')`.
 
 The HTTP interfaces in Node.js are designed to support many features

doc/api/http2.md

@@ -10,6 +10,8 @@ changes:
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/http2.js -->
+
 The `http2` module provides an implementation of the [HTTP/2][] protocol. It
 can be accessed using:
 

doc/api/https.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/https.js -->
+
 HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a
 separate module.
 

doc/api/inspector.md

@@ -4,6 +4,8 @@
 
 > Stability: 1 - Experimental
 
+<!-- source_link=lib/inspector.js -->
+
 The `inspector` module provides an API for interacting with the V8 inspector.
 
 It can be accessed using:

doc/api/net.md

@@ -5,6 +5,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/net.js -->
+
 The `net` module provides an asynchronous network API for creating stream-based
 TCP or [IPC][] servers ([`net.createServer()`][]) and clients
 ([`net.createConnection()`][]).

doc/api/os.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/os.js -->
+
 The `os` module provides operating system-related utility methods and
 properties. It can be accessed using:
 

doc/api/path.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/path.js -->
+
 The `path` module provides utilities for working with file and directory paths.
 It can be accessed using:
 

doc/api/perf_hooks.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/perf_hooks.js -->
+
 This module provides an implementation of a subset of the W3C
 [Web Performance APIs][] as well as additional APIs for
 Node.js-specific performance measurements.

doc/api/process.md

@@ -3,6 +3,8 @@
 <!-- introduced_in=v0.10.0 -->
 <!-- type=global -->
 
+<!-- source_link=lib/process.js -->
+
 The `process` object is a `global` that provides information about, and control
 over, the current Node.js process. As a global, it is always available to
 Node.js applications without using `require()`. It can also be explicitly

doc/api/punycode.md

@@ -10,6 +10,8 @@ changes:
 
 > Stability: 0 - Deprecated
 
+<!-- source_link=lib/punycode.js -->
+
 **The version of the punycode module bundled in Node.js is being deprecated**.
 In a future major version of Node.js this module will be removed. Users
 currently depending on the `punycode` module should switch to using the

doc/api/querystring.md

@@ -6,6 +6,8 @@
 
 <!--name=querystring-->
 
+<!-- source_link=lib/querystring.js -->
+
 The `querystring` module provides utilities for parsing and formatting URL
 query strings. It can be accessed using:
 

doc/api/readline.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/readline.js -->
+
 The `readline` module provides an interface for reading data from a [Readable][]
 stream (such as [`process.stdin`][]) one line at a time. It can be accessed
 using:

doc/api/repl.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/repl.js -->
+
 The `repl` module provides a Read-Eval-Print-Loop (REPL) implementation that
 is available both as a standalone program or includible in other applications.
 It can be accessed using:

doc/api/stream.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/stream.js -->
+
 A stream is an abstract interface for working with streaming data in Node.js.
 The `stream` module provides an API for implementing the stream interface.
 

doc/api/string_decoder.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/string_decoder.js -->
+
 The `string_decoder` module provides an API for decoding `Buffer` objects into
 strings in a manner that preserves encoded multi-byte UTF-8 and UTF-16
 characters. It can be accessed using:

doc/api/timers.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/timers.js -->
+
 The `timer` module exposes a global API for scheduling functions to
 be called at some future period of time. Because the timer functions are
 globals, there is no need to call `require('timers')` to use the API.

doc/api/tls.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/tls.js -->
+
 The `tls` module provides an implementation of the Transport Layer Security
 (TLS) and Secure Socket Layer (SSL) protocols that is built on top of OpenSSL.
 The module can be accessed using:

doc/api/tracing.md

@@ -4,6 +4,8 @@
 
 > Stability: 1 - Experimental
 
+<!-- source_link=lib/trace_events.js -->
+
 The `trace_events` module provides a mechanism to centralize tracing information
 generated by V8, Node.js core, and userspace code.
 

doc/api/tty.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/tty.js -->
+
 The `tty` module provides the `tty.ReadStream` and `tty.WriteStream` classes.
 In most cases, it will not be necessary or possible to use this module directly.
 However, it can be accessed using:

doc/api/url.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/url.js -->
+
 The `url` module provides utilities for URL resolution and parsing. It can be
 accessed using:
 

doc/api/util.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/util.js -->
+
 The `util` module supports the needs of Node.js internal APIs. Many of the
 utilities are useful for application and module developers as well. To access
 it:

doc/api/v8.md

@@ -2,6 +2,8 @@
 
 <!--introduced_in=v4.0.0-->
 
+<!-- source_link=lib/v8.js -->
+
 The `v8` module exposes APIs that are specific to the version of [V8][]
 built into the Node.js binary. It can be accessed using:
 

doc/api/vm.md

@@ -6,6 +6,8 @@
 
 <!--name=vm-->
 
+<!-- source_link=lib/vm.js -->
+
 The `vm` module enables compiling and running code within V8 Virtual
 Machine contexts. **The `vm` module is not a security mechanism. Do
 not use it to run untrusted code**.

doc/api/wasi.md

@@ -4,6 +4,8 @@
 
 > Stability: 1 - Experimental
 
+<!-- source_link=lib/wasi.js -->
+
 The WASI API provides an implementation of the [WebAssembly System Interface][]
 specification. WASI gives sandboxed WebAssembly applications access to the
 underlying operating system via a collection of POSIX-like functions.

doc/api/worker_threads.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/worker_threads.js -->
+
 The `worker_threads` module enables the use of threads that execute JavaScript
 in parallel. To access it:
 

doc/api/zlib.md

@@ -4,6 +4,8 @@
 
 > Stability: 2 - Stable
 
+<!-- source_link=lib/zlib.js -->
+
 The `zlib` module provides compression functionality implemented using Gzip,
 Deflate/Inflate, and Brotli.
 

test/doctool/test-doctool-html.js

@@ -41,7 +41,7 @@ function toHTML({ input, filename, nodeVersion, versions }) {
     .use(replaceLinks, { filename, linksMapper: testLinksMapper })
     .use(markdown)
     .use(html.firstHeader)
-    .use(html.preprocessText)
+    .use(html.preprocessText, { nodeVersion })
     .use(html.preprocessElements, { filename })
     .use(html.buildToc, { filename, apilinks: {} })
     .use(remark2rehype, { allowDangerousHTML: true })

tools/doc/common.js

@@ -7,6 +7,10 @@ function isYAMLBlock(text) {
   return /^<!-- YAML/.test(text);
 }
 
+function isSourceLink(text) {
+  return /^<!-- source_link=([^\s/]+\/)+\w+\.\w+ -->/.test(text);
+}
+
 function arrify(value) {
   return Array.isArray(value) ? value : [value];
 }
@@ -43,4 +47,4 @@ function extractAndParseYAML(text) {
   return meta;
 }
 
-module.exports = { arrify, isYAMLBlock, extractAndParseYAML };
+module.exports = { arrify, isYAMLBlock, isSourceLink, extractAndParseYAML };

tools/doc/generate.js

@@ -82,7 +82,7 @@ async function main() {
   const content = await unified()
     .use(replaceLinks, { filename, linksMapper })
     .use(markdown)
-    .use(html.preprocessText)
+    .use(html.preprocessText, { nodeVersion })
     .use(json.jsonAPI, { filename })
     .use(html.firstHeader)
     .use(html.preprocessElements, { filename })

tools/doc/html.js

@@ -104,10 +104,13 @@ function firstHeader() {
 
 // Handle general body-text replacements.
 // For example, link man page references to the actual page.
-function preprocessText() {
+function preprocessText({ nodeVersion }) {
   return (tree) => {
     visit(tree, null, (node) => {
-      if (node.type === 'text' && node.value) {
+      if (common.isSourceLink(node.value)) {
+        const [path] = node.value.match(/(?<=<!-- source_link=).*(?= -->)/);
+        node.value = `<p><strong>Source Code:</strong> <a href="https://github.com/nodejs/node/blob/${nodeVersion}/${path}">${path}</a></p>`;
+      } else if (node.type === 'text' && node.value) {
         const value = linkJsTypeDocs(linkManPages(node.value));
         if (value !== node.value) {
           node.type = 'html';