docs: add doc-check to all modules (#2419)

Adds the `doc-check` script to all modules to ensure ts docs compile. Also runs during CI.
libp2p · Feb 20, 2024 · 6cdb243 · 6cdb243
1 parent e1c0137
commit 6cdb243
Show file tree

Hide file tree

Showing 114 changed files with 1,415 additions and 892 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -34,7 +34,8 @@ jobs:
     - uses: ipfs/aegir/actions/cache-node-modules@master
     - run: npm run --if-present lint
     - run: npm run --if-present dep-check
-    - run: cd doc && npm run doc-check
+    - run: npm run --if-present docs:no-publish
+    - run: npm run --if-present doc-check
   test-node:
     needs: build
     runs-on: ${{ matrix.os }}

diff --git a/.gitignore b/.gitignore
@@ -5,6 +5,8 @@ dist
 node_modules
 package-lock.json
 yarn.lock
+.tmp-compiled-docs
+tsconfig-doc-check.aegir.json
 
 # IDE
 .DS_Store

diff --git a/doc/package.json b/doc/package.json
@@ -23,15 +23,8 @@
   "scripts": {
     "doc-check": "aegir doc-check"
   },
-  "dependencies": {
-    "@chainsafe/libp2p-yamux": "^6.0.1",
-    "@libp2p/interface": "^1.1.2",
-    "@libp2p/mplex": "^10.0.13",
-    "@libp2p/prometheus-metrics": "^3.0.13",
-    "@libp2p/tcp": "^9.0.13",
-    "aegir": "^42.2.3",
-    "libp2p": "^1.2.1",
-    "prom-client": "^15.1.0"
+  "devDependencies": {
+    "aegir": "^42.2.4"
   },
   "private": true
 }
diff --git a/interop/package.json b/interop/package.json
@@ -56,7 +56,7 @@
   },
   "dependencies": {
     "@chainsafe/libp2p-noise": "^15.0.0",
-    "@chainsafe/libp2p-yamux": "^6.0.1",
+    "@chainsafe/libp2p-yamux": "^6.0.2",
     "@libp2p/circuit-relay-v2": "^1.0.15",
     "@libp2p/identify": "^1.0.14",
     "@libp2p/mplex": "^10.0.15",
@@ -67,7 +67,7 @@
     "@libp2p/webtransport": "^4.0.19",
     "@multiformats/mafmt": "^12.1.6",
     "@multiformats/multiaddr": "^12.1.14",
-    "aegir": "^42.2.3",
+    "aegir": "^42.2.4",
     "libp2p": "^1.2.3",
     "redis": "^4.6.13"
   },

diff --git a/package.json b/package.json
@@ -28,6 +28,7 @@
     "clean": "aegir run clean",
     "lint": "aegir run lint",
     "dep-check": "aegir run dep-check",
+    "doc-check": "aegir run doc-check",
     "release": "run-s build docs:no-publish npm:release docs",
     "npm:release": "aegir exec --bail false npm -- publish",
     "release:rc": "aegir release-rc",

diff --git a/packages/connection-encrypter-plaintext/README.md b/packages/connection-encrypter-plaintext/README.md
@@ -1,3 +1,5 @@
+# @libp2p/plaintext
+
 [![libp2p.io](https://img.shields.io/badge/project-libp2p-yellow.svg?style=flat-square)](http://libp2p.io/)
 [![Discuss](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg?style=flat-square)](https://discuss.libp2p.io)
 [![codecov](https://img.shields.io/codecov/c/github/libp2p/js-libp2p.svg?style=flat-square)](https://codecov.io/gh/libp2p/js-libp2p)
@@ -7,6 +9,21 @@
 
 # About
 
+<!--
+
+!IMPORTANT!
+
+Everything in this README between "# About" and "# Install" is automatically
+generated and will be overwritten the next time the doc generator is run.
+
+To make changes to this section, please update the @packageDocumentation section
+of src/index.js or src/index.ts
+
+To experiment with formatting, please run "npm run docs" from the root of this
+repo and examine the changes made.
+
+-->
+
 A connection encrypter that does no connection encryption.
 
 This should not be used in production should be used for research purposes only.

diff --git a/packages/connection-encrypter-plaintext/package.json b/packages/connection-encrypter-plaintext/package.json
@@ -48,7 +48,8 @@
     "test:firefox": "aegir test -t browser -- --browser firefox",
     "test:firefox-webworker": "aegir test -t webworker -- --browser firefox",
     "test:node": "aegir test -t node --cov",
-    "dep-check": "aegir dep-check"
+    "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check"
   },
   "dependencies": {
     "@libp2p/interface": "^1.1.3",
@@ -63,7 +64,7 @@
     "@libp2p/logger": "^4.0.6",
     "@libp2p/peer-id-factory": "^4.0.6",
     "@multiformats/multiaddr": "^12.1.14",
-    "aegir": "^42.2.3",
+    "aegir": "^42.2.4",
     "protons": "^7.5.0",
     "sinon": "^17.0.1"
   },

diff --git a/packages/connection-encrypter-tls/README.md b/packages/connection-encrypter-tls/README.md
@@ -1,3 +1,5 @@
+# @libp2p/tls
+
 [![libp2p.io](https://img.shields.io/badge/project-libp2p-yellow.svg?style=flat-square)](http://libp2p.io/)
 [![Discuss](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg?style=flat-square)](https://discuss.libp2p.io)
 [![codecov](https://img.shields.io/codecov/c/github/libp2p/js-libp2p.svg?style=flat-square)](https://codecov.io/gh/libp2p/js-libp2p)
@@ -7,6 +9,21 @@
 
 # About
 
+<!--
+
+!IMPORTANT!
+
+Everything in this README between "# About" and "# Install" is automatically
+generated and will be overwritten the next time the doc generator is run.
+
+To make changes to this section, please update the @packageDocumentation section
+of src/index.js or src/index.ts
+
+To experiment with formatting, please run "npm run docs" from the root of this
+repo and examine the changes made.
+
+-->
+
 Implements the spec at <https://github.com/libp2p/specs/blob/master/tls/tls.md>
 
 ## Example

diff --git a/packages/connection-encrypter-tls/package.json b/packages/connection-encrypter-tls/package.json
@@ -44,7 +44,8 @@
     "generate": "protons ./src/pb/index.proto",
     "lint": "aegir lint",
     "test:node": "aegir test -t node --cov",
-    "dep-check": "aegir dep-check"
+    "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check"
   },
   "dependencies": {
     "@libp2p/crypto": "^4.0.2",
@@ -59,14 +60,14 @@
     "it-stream-types": "^2.0.1",
     "protons-runtime": "^5.4.0",
     "uint8arraylist": "^2.4.8",
-    "uint8arrays": "^5.0.1"
+    "uint8arrays": "^5.0.2"
   },
   "devDependencies": {
     "@libp2p/interface-compliance-tests": "^5.3.1",
     "@libp2p/logger": "^4.0.6",
     "@libp2p/peer-id-factory": "^4.0.6",
     "@multiformats/multiaddr": "^12.1.14",
-    "aegir": "^42.2.3",
+    "aegir": "^42.2.4",
     "protons": "^7.5.0",
     "sinon": "^17.0.1"
   },

diff --git a/packages/crypto/README.md b/packages/crypto/README.md
@@ -1,10 +1,35 @@
+# @libp2p/crypto
+
 [![libp2p.io](https://img.shields.io/badge/project-libp2p-yellow.svg?style=flat-square)](http://libp2p.io/)
 [![Discuss](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg?style=flat-square)](https://discuss.libp2p.io)
 [![codecov](https://img.shields.io/codecov/c/github/libp2p/js-libp2p.svg?style=flat-square)](https://codecov.io/gh/libp2p/js-libp2p)
 [![CI](https://img.shields.io/github/actions/workflow/status/libp2p/js-libp2p/main.yml?branch=main\&style=flat-square)](https://github.com/libp2p/js-libp2p/actions/workflows/main.yml?query=branch%3Amain)
 
 > Crypto primitives for libp2p
 
+# About
+
+<!--
+
+!IMPORTANT!
+
+Everything in this README between "# About" and "# Install" is automatically
+generated and will be overwritten the next time the doc generator is run.
+
+To make changes to this section, please update the @packageDocumentation section
+of src/index.js or src/index.ts
+
+To experiment with formatting, please run "npm run docs" from the root of this
+repo and examine the changes made.
+
+-->
+
+The `libp2p-crypto` library depends on the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) in the browser. Web Crypto is available in all modern browsers, however browsers restrict its usage to [Secure Contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts).
+
+*This means you will not be able to use some `@libp2p/crypto` functions in the browser when the page is served over HTTP.*
+
+To enable the Web Crypto API and allow `@libp2p/crypto` to work fully, please serve your page over HTTPS.
+
 # Install
 
 ```console

diff --git a/packages/crypto/package.json b/packages/crypto/package.json
@@ -71,6 +71,7 @@
     "clean": "aegir clean",
     "lint": "aegir lint",
     "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check",
     "build": "aegir build",
     "test": "aegir test",
     "test:chrome": "aegir test -t browser",
@@ -87,14 +88,14 @@
     "@noble/curves": "^1.3.0",
     "@noble/hashes": "^1.3.3",
     "asn1js": "^3.0.5",
-    "multiformats": "^13.0.1",
+    "multiformats": "^13.1.0",
     "protons-runtime": "^5.4.0",
     "uint8arraylist": "^2.4.8",
-    "uint8arrays": "^5.0.1"
+    "uint8arrays": "^5.0.2"
   },
   "devDependencies": {
     "@types/mocha": "^10.0.6",
-    "aegir": "^42.2.3",
+    "aegir": "^42.2.4",
     "benchmark": "^2.1.4",
     "protons": "^7.5.0"
   },

diff --git a/packages/crypto/src/hmac/index.ts b/packages/crypto/src/hmac/index.ts
@@ -5,7 +5,7 @@
  *
  * @example
  *
- * ```js
+ * ```TypeScript
  * import { create } from '@libp2p/hmac'
  *
  * const hash = 'SHA1' // 'SHA256' || 'SHA512'

diff --git a/packages/integration-tests/package.json b/packages/integration-tests/package.json
@@ -35,50 +35,50 @@
   "devDependencies": {
     "@chainsafe/libp2p-gossipsub": "^11.2.1",
     "@chainsafe/libp2p-noise": "^15.0.0",
-    "@chainsafe/libp2p-yamux": "^6.0.1",
-    "@libp2p/bootstrap": "^10.0.13",
-    "@libp2p/circuit-relay-v2": "^1.0.13",
-    "@libp2p/crypto": "^4.0.1",
-    "@libp2p/daemon-client": "^8.0.1",
-    "@libp2p/daemon-server": "^7.0.1",
-    "@libp2p/dcutr": "^1.0.10",
-    "@libp2p/fetch": "^1.0.9",
-    "@libp2p/floodsub": "^9.0.9",
-    "@libp2p/identify": "^1.0.12",
-    "@libp2p/interface": "^1.1.2",
-    "@libp2p/interface-compliance-tests": "^5.2.0",
-    "@libp2p/interface-internal": "^1.0.7",
+    "@chainsafe/libp2p-yamux": "^6.0.2",
+    "@libp2p/bootstrap": "^10.0.15",
+    "@libp2p/circuit-relay-v2": "^1.0.15",
+    "@libp2p/crypto": "^4.0.2",
+    "@libp2p/daemon-client": "^8.0.4",
+    "@libp2p/daemon-server": "^7.0.4",
+    "@libp2p/dcutr": "^1.0.12",
+    "@libp2p/fetch": "^1.0.10",
+    "@libp2p/floodsub": "^9.0.11",
+    "@libp2p/identify": "^1.0.14",
+    "@libp2p/interface": "^1.1.3",
+    "@libp2p/interface-compliance-tests": "^5.3.1",
+    "@libp2p/interface-internal": "^1.0.8",
     "@libp2p/interop": "^11.0.0",
-    "@libp2p/kad-dht": "^12.0.5",
-    "@libp2p/logger": "^4.0.5",
-    "@libp2p/mdns": "^10.0.13",
-    "@libp2p/mplex": "^10.0.13",
-    "@libp2p/peer-id": "^4.0.5",
-    "@libp2p/peer-id-factory": "^4.0.5",
-    "@libp2p/ping": "^1.0.10",
-    "@libp2p/plaintext": "^1.0.13",
-    "@libp2p/tcp": "^9.0.13",
+    "@libp2p/kad-dht": "^12.0.7",
+    "@libp2p/logger": "^4.0.6",
+    "@libp2p/mdns": "^10.0.15",
+    "@libp2p/mplex": "^10.0.15",
+    "@libp2p/peer-id": "^4.0.6",
+    "@libp2p/peer-id-factory": "^4.0.6",
+    "@libp2p/ping": "^1.0.11",
+    "@libp2p/plaintext": "^1.0.15",
+    "@libp2p/tcp": "^9.0.15",
     "@libp2p/tls": "^0.0.0",
-    "@libp2p/webrtc": "^4.0.17",
-    "@libp2p/websockets": "^8.0.13",
+    "@libp2p/webrtc": "^4.0.19",
+    "@libp2p/websockets": "^8.0.15",
     "@multiformats/mafmt": "^12.1.6",
     "@multiformats/multiaddr": "^12.1.14",
-    "aegir": "^42.2.3",
+    "aegir": "^42.2.4",
     "delay": "^6.0.0",
     "execa": "^8.0.1",
     "go-libp2p": "^1.1.1",
     "it-all": "^3.0.4",
     "it-pipe": "^3.0.1",
-    "libp2p": "^1.2.1",
+    "libp2p": "^1.2.3",
     "merge-options": "^3.0.4",
-    "multiformats": "^13.0.1",
+    "multiformats": "^13.1.0",
     "p-defer": "^4.0.0",
     "p-event": "^6.0.0",
     "p-retry": "^6.2.0",
     "p-wait-for": "^5.0.2",
     "sinon": "^17.0.1",
     "uint8arraylist": "^2.4.8",
-    "uint8arrays": "^5.0.1",
+    "uint8arrays": "^5.0.2",
     "wherearewe": "^2.0.1"
   },
   "browser": {

diff --git a/packages/interface-compliance-tests/README.md b/packages/interface-compliance-tests/README.md
@@ -1,3 +1,5 @@
+# @libp2p/interface-compliance-tests
+
 [![libp2p.io](https://img.shields.io/badge/project-libp2p-yellow.svg?style=flat-square)](http://libp2p.io/)
 [![Discuss](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg?style=flat-square)](https://discuss.libp2p.io)
 [![codecov](https://img.shields.io/codecov/c/github/libp2p/js-libp2p.svg?style=flat-square)](https://codecov.io/gh/libp2p/js-libp2p)

diff --git a/packages/interface-compliance-tests/package.json b/packages/interface-compliance-tests/package.json
@@ -100,6 +100,7 @@
     "clean": "aegir clean",
     "lint": "aegir lint",
     "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check",
     "build": "aegir build",
     "generate": "protons src/stream-muxer/fixtures/pb/message.proto",
     "test": "aegir test",
@@ -121,7 +122,7 @@
     "@libp2p/utils": "^5.2.5",
     "@multiformats/multiaddr": "^12.1.14",
     "abortable-iterator": "^5.0.1",
-    "aegir": "^42.2.3",
+    "aegir": "^42.2.4",
     "delay": "^6.0.0",
     "it-all": "^3.0.4",
     "it-byte-stream": "^1.0.8",
@@ -142,7 +143,7 @@
     "protons-runtime": "^5.4.0",
     "sinon": "^17.0.1",
     "uint8arraylist": "^2.4.8",
-    "uint8arrays": "^5.0.1"
+    "uint8arrays": "^5.0.2"
   },
   "devDependencies": {
     "protons": "^7.5.0"

diff --git a/packages/interface-internal/README.md b/packages/interface-internal/README.md
@@ -1,3 +1,5 @@
+# @libp2p/interface-internal
+
 [![libp2p.io](https://img.shields.io/badge/project-libp2p-yellow.svg?style=flat-square)](http://libp2p.io/)
 [![Discuss](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg?style=flat-square)](https://discuss.libp2p.io)
 [![codecov](https://img.shields.io/codecov/c/github/libp2p/js-libp2p.svg?style=flat-square)](https://codecov.io/gh/libp2p/js-libp2p)

diff --git a/packages/interface-internal/package.json b/packages/interface-internal/package.json
@@ -44,6 +44,7 @@
     "clean": "aegir clean",
     "lint": "aegir lint",
     "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check",
     "build": "aegir build"
   },
   "dependencies": {
@@ -53,7 +54,7 @@
     "uint8arraylist": "^2.4.8"
   },
   "devDependencies": {
-    "aegir": "^42.2.3"
+    "aegir": "^42.2.4"
   },
   "sideEffects": false
 }