From ac4ff5a00a034fb3dec9e584cbe55b4769791771 Mon Sep 17 00:00:00 2001 From: "fryorcraken.eth" Date: Wed, 21 Dec 2022 00:48:16 +1100 Subject: [PATCH] chore: fix links in docs, treat doc warnings as errors --- package-lock.json | 68 ++++++++++++------- package.json | 5 +- packages/core/CHANGELOG.md | 4 ++ packages/core/src/index.ts | 5 +- packages/core/src/lib/message/index.ts | 2 + .../src/lib/message/topic_only_message.ts | 6 +- packages/core/src/lib/relay/index.ts | 8 +-- packages/core/src/lib/wait_for_remote_peer.ts | 4 +- packages/create/CHANGELOG.md | 4 ++ packages/create/src/index.ts | 13 ++-- packages/dns-discovery/src/index.ts | 4 +- packages/peer-exchange/src/index.ts | 2 +- packages/proto/src/index.ts | 1 + typedoc.cjs | 16 +++++ typedoc.json | 19 ------ 15 files changed, 94 insertions(+), 67 deletions(-) create mode 100644 packages/core/src/lib/message/index.ts create mode 100644 typedoc.cjs delete mode 100644 typedoc.json diff --git a/package-lock.json b/package-lock.json index 843bdd72ed..a1e412e8b3 100644 --- a/package-lock.json +++ b/package-lock.json @@ -32,7 +32,8 @@ "multi-semantic-release": "^3.0.1", "semantic-release": "^19.0.5", "size-limit": "^8.1.0", - "typedoc": "^0.23.19" + "typedoc": "^0.23.23", + "typedoc-plugin-resolve-crossmodule-references": "^0.3.3" } }, "node_modules/@achingbrain/ip-address": { @@ -15111,9 +15112,9 @@ } }, "node_modules/marked": { - "version": "4.1.1", - "resolved": "https://registry.npmjs.org/marked/-/marked-4.1.1.tgz", - "integrity": "sha512-0cNMnTcUJPxbA6uWmCmjWz4NJRe/0Xfk2NhXCUHjew9qJzFN20krFnsUe7QynwqOwa5m1fZ4UDg0ycKFVC0ccw==", + "version": "4.2.4", + "resolved": "https://registry.npmjs.org/marked/-/marked-4.2.4.tgz", + "integrity": "sha512-Wcc9ikX7Q5E4BYDPvh1C6QNSxrjC9tBgz+A/vAhp59KXUgachw++uMvMKiSW8oA85nopmPZcEvBoex/YLMsiyA==", "bin": { "marked": "bin/marked.js" }, @@ -25773,14 +25774,14 @@ } }, "node_modules/typedoc": { - "version": "0.23.19", - "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.23.19.tgz", - "integrity": "sha512-70jPL0GQnSJtgQqI7ifOWxpTXrB3sxc4SWPPRn3K0wdx3txI6ZIT/ZYMF39dNg2Gjmql45cO+cAKXJp0TpqOVA==", + "version": "0.23.23", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.23.23.tgz", + "integrity": "sha512-cg1YQWj+/BU6wq74iott513U16fbrPCbyYs04PHZgvoKJIc6EY4xNobyDZh4KMfRGW8Yjv6wwIzQyoqopKOUGw==", "dev": true, "dependencies": { "lunr": "^2.3.9", - "marked": "^4.0.19", - "minimatch": "^5.1.0", + "marked": "^4.2.4", + "minimatch": "^5.1.1", "shiki": "^0.11.1" }, "bin": { @@ -25790,7 +25791,19 @@ "node": ">= 14.14" }, "peerDependencies": { - "typescript": "4.6.x || 4.7.x || 4.8.x" + "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x" + } + }, + "node_modules/typedoc-plugin-resolve-crossmodule-references": { + "version": "0.3.3", + "resolved": "https://registry.npmjs.org/typedoc-plugin-resolve-crossmodule-references/-/typedoc-plugin-resolve-crossmodule-references-0.3.3.tgz", + "integrity": "sha512-ZWWBy2WR8z9a6iXYGlyB3KrpV+JDdZv1mndYU6Eh6mInrfMCrQJi3Y5K9ihMBfuaBGB//le1nEmQLgzU3IO+dw==", + "dev": true, + "engines": { + "node": ">=14" + }, + "peerDependencies": { + "typedoc": ">=0.22 <=0.23" } }, "node_modules/typedoc/node_modules/brace-expansion": { @@ -25803,9 +25816,9 @@ } }, "node_modules/typedoc/node_modules/minimatch": { - "version": "5.1.0", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.0.tgz", - "integrity": "sha512-9TPBGGak4nHfGZsPBohm9AWg6NoT7QTCehS3BIJABslyZbzxfV78QM2Y6+i741OPZIafFAaiiEMh5OyIrJPgtg==", + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.1.tgz", + "integrity": "sha512-362NP+zlprccbEt/SkxKfRMHnNY85V74mVnpUpNyr3F35covl09Kec7/sEFLt3RA4oXmewtoaanoIf67SE5Y5g==", "dev": true, "dependencies": { "brace-expansion": "^2.0.1" @@ -38940,9 +38953,9 @@ "integrity": "sha512-Z1NL3Tb1M9wH4XESsCDEksWoKTdlUafKc4pt0GRwjUyXaCFZ+dc3g2erqB6zm3szA2IUSi7VnPI+o/9jnxh9hw==" }, "marked": { - "version": "4.1.1", - "resolved": "https://registry.npmjs.org/marked/-/marked-4.1.1.tgz", - "integrity": "sha512-0cNMnTcUJPxbA6uWmCmjWz4NJRe/0Xfk2NhXCUHjew9qJzFN20krFnsUe7QynwqOwa5m1fZ4UDg0ycKFVC0ccw==" + "version": "4.2.4", + "resolved": "https://registry.npmjs.org/marked/-/marked-4.2.4.tgz", + "integrity": "sha512-Wcc9ikX7Q5E4BYDPvh1C6QNSxrjC9tBgz+A/vAhp59KXUgachw++uMvMKiSW8oA85nopmPZcEvBoex/YLMsiyA==" }, "marked-terminal": { "version": "5.1.1", @@ -46347,14 +46360,14 @@ } }, "typedoc": { - "version": "0.23.19", - "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.23.19.tgz", - "integrity": "sha512-70jPL0GQnSJtgQqI7ifOWxpTXrB3sxc4SWPPRn3K0wdx3txI6ZIT/ZYMF39dNg2Gjmql45cO+cAKXJp0TpqOVA==", + "version": "0.23.23", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.23.23.tgz", + "integrity": "sha512-cg1YQWj+/BU6wq74iott513U16fbrPCbyYs04PHZgvoKJIc6EY4xNobyDZh4KMfRGW8Yjv6wwIzQyoqopKOUGw==", "dev": true, "requires": { "lunr": "^2.3.9", - "marked": "^4.0.19", - "minimatch": "^5.1.0", + "marked": "^4.2.4", + "minimatch": "^5.1.1", "shiki": "^0.11.1" }, "dependencies": { @@ -46368,9 +46381,9 @@ } }, "minimatch": { - "version": "5.1.0", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.0.tgz", - "integrity": "sha512-9TPBGGak4nHfGZsPBohm9AWg6NoT7QTCehS3BIJABslyZbzxfV78QM2Y6+i741OPZIafFAaiiEMh5OyIrJPgtg==", + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.1.tgz", + "integrity": "sha512-362NP+zlprccbEt/SkxKfRMHnNY85V74mVnpUpNyr3F35covl09Kec7/sEFLt3RA4oXmewtoaanoIf67SE5Y5g==", "dev": true, "requires": { "brace-expansion": "^2.0.1" @@ -46378,6 +46391,13 @@ } } }, + "typedoc-plugin-resolve-crossmodule-references": { + "version": "0.3.3", + "resolved": "https://registry.npmjs.org/typedoc-plugin-resolve-crossmodule-references/-/typedoc-plugin-resolve-crossmodule-references-0.3.3.tgz", + "integrity": "sha512-ZWWBy2WR8z9a6iXYGlyB3KrpV+JDdZv1mndYU6Eh6mInrfMCrQJi3Y5K9ihMBfuaBGB//le1nEmQLgzU3IO+dw==", + "dev": true, + "requires": {} + }, "typescript": { "version": "4.8.4", "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.8.4.tgz", diff --git a/package.json b/package.json index 78c438c67e..4e21b7f49f 100644 --- a/package.json +++ b/package.json @@ -28,7 +28,7 @@ "proto": "npm run proto --workspaces --if-present", "deploy": "node ci/deploy.js", "doc": "run-s doc:*", - "doc:html": "typedoc # --treatWarningsAsErrors", + "doc:html": "typedoc --options typedoc.cjs --treatWarningsAsErrors", "doc:cname": "echo 'js.waku.org' > docs/CNAME", "release": "multi-semantic-release" }, @@ -46,7 +46,8 @@ "multi-semantic-release": "^3.0.1", "semantic-release": "^19.0.5", "size-limit": "^8.1.0", - "typedoc": "^0.23.19" + "typedoc": "^0.23.23", + "typedoc-plugin-resolve-crossmodule-references": "^0.3.3" }, "release": { "branches": [ diff --git a/packages/core/CHANGELOG.md b/packages/core/CHANGELOG.md index 6bd54c7e07..b4f5fb8b81 100644 --- a/packages/core/CHANGELOG.md +++ b/packages/core/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Fixed + +- Documentation links. + ## [@waku/core@0.0.8] - 2022-12-19 ### Fixed diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index e704ec4c40..51d8b0c2e8 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -6,9 +6,10 @@ export { createDecoder, DecodedMessage, } from "./lib/message/version_0.js"; +export * as message from "./lib/message/index.js"; export * as waku from "./lib/waku.js"; -export { WakuNode } from "./lib/waku.js"; +export { WakuNode, WakuOptions } from "./lib/waku.js"; export * as waku_filter from "./lib/filter/index.js"; export { wakuFilter } from "./lib/filter/index.js"; @@ -17,7 +18,7 @@ export * as waku_light_push from "./lib/light_push/index.js"; export { wakuLightPush, LightPushCodec } from "./lib/light_push/index.js"; export * as waku_relay from "./lib/relay/index.js"; -export { wakuRelay } from "./lib/relay/index.js"; +export { wakuRelay, RelayCreateOptions } from "./lib/relay/index.js"; export * as waku_store from "./lib/store/index.js"; export { diff --git a/packages/core/src/lib/message/index.ts b/packages/core/src/lib/message/index.ts new file mode 100644 index 0000000000..391edc8b83 --- /dev/null +++ b/packages/core/src/lib/message/index.ts @@ -0,0 +1,2 @@ +export * as version_0 from "./version_0.js"; +export * as topic_only_message from "./topic_only_message.js"; diff --git a/packages/core/src/lib/message/topic_only_message.ts b/packages/core/src/lib/message/topic_only_message.ts index fadf956700..e45bf07b22 100644 --- a/packages/core/src/lib/message/topic_only_message.ts +++ b/packages/core/src/lib/message/topic_only_message.ts @@ -3,7 +3,7 @@ import type { IDecoder, IProtoMessage, } from "@waku/interfaces"; -import { proto_topic_only_message as proto } from "@waku/proto"; +import { TopicOnlyMessage as ProtoTopicOnlyMessage } from "@waku/proto"; import debug from "debug"; const log = debug("waku:message:topic-only"); @@ -14,7 +14,7 @@ export class TopicOnlyMessage implements IDecodedMessage { public timestamp: undefined; public ephemeral: undefined; - constructor(private proto: proto.TopicOnlyMessage) {} + constructor(private proto: ProtoTopicOnlyMessage) {} get contentTopic(): string { return this.proto.contentTopic ?? ""; @@ -25,7 +25,7 @@ export class TopicOnlyDecoder implements IDecoder { public contentTopic = ""; fromWireToProtoObj(bytes: Uint8Array): Promise { - const protoMessage = proto.TopicOnlyMessage.decode(bytes); + const protoMessage = ProtoTopicOnlyMessage.decode(bytes); log("Message decoded", protoMessage); return Promise.resolve({ contentTopic: protoMessage.contentTopic, diff --git a/packages/core/src/lib/relay/index.ts b/packages/core/src/lib/relay/index.ts index dda5664ab6..6366a6151c 100644 --- a/packages/core/src/lib/relay/index.ts +++ b/packages/core/src/lib/relay/index.ts @@ -30,7 +30,7 @@ export type Observer = { callback: Callback; }; -export type CreateOptions = { +export interface RelayCreateOptions extends GossipsubOpts { /** * The PubSub Topic to use. Defaults to {@link DefaultPubSubTopic}. * @@ -45,7 +45,7 @@ export type CreateOptions = { * @default {@link DefaultPubSubTopic} */ pubSubTopic?: string; -} & GossipsubOpts; +} /** * Implements the [Waku v2 Relay protocol](https://rfc.vac.dev/spec/11/). @@ -66,7 +66,7 @@ class Relay extends GossipSub implements IRelay { constructor( components: GossipSubComponents, - options?: Partial + options?: Partial ) { options = Object.assign(options ?? {}, { // Ensure that no signature is included nor expected in the messages. @@ -188,7 +188,7 @@ class Relay extends GossipSub implements IRelay { Relay.multicodec = constants.RelayCodecs[constants.RelayCodecs.length - 1]; export function wakuRelay( - init: Partial = {} + init: Partial = {} ): (components: GossipSubComponents) => IRelay { return (components: GossipSubComponents) => new Relay(components, init); } diff --git a/packages/core/src/lib/wait_for_remote_peer.ts b/packages/core/src/lib/wait_for_remote_peer.ts index 60302587f7..db0e05debc 100644 --- a/packages/core/src/lib/wait_for_remote_peer.ts +++ b/packages/core/src/lib/wait_for_remote_peer.ts @@ -14,8 +14,8 @@ const log = debug("waku:wait-for-remote-peer"); /** * Wait for a remote peer to be ready given the passed protocols. * Must be used after attempting to connect to nodes, using - * {@link index.waku.WakuNode.dial} or a bootstrap method with - * {@link lib/create_waku.createLightNode}. + * {@link @waku/core.WakuNode.dial} or a bootstrap method with + * {@link @waku/create.createLightNode}. * * If the passed protocols is a GossipSub protocol, then it resolves only once * a peer is in a mesh, to help ensure that other peers will send and receive diff --git a/packages/create/CHANGELOG.md b/packages/create/CHANGELOG.md index 43ca0fb9b7..9cd9216265 100644 --- a/packages/create/CHANGELOG.md +++ b/packages/create/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Fixed + +- Documentation links. + ## [0.0.6] - 2022-12-19 ### Fixed diff --git a/packages/create/src/index.ts b/packages/create/src/index.ts index 22b38d55a4..158953364c 100644 --- a/packages/create/src/index.ts +++ b/packages/create/src/index.ts @@ -5,11 +5,11 @@ import { mplex } from "@libp2p/mplex"; import { webSockets } from "@libp2p/websockets"; import { all as filterAll } from "@libp2p/websockets/filters"; import { - waku, - waku_relay, + RelayCreateOptions, wakuFilter, wakuLightPush, WakuNode, + WakuOptions, wakuRelay, wakuStore, } from "@waku/core"; @@ -24,9 +24,6 @@ import type { Libp2pComponents } from "./libp2p_components.js"; export { Libp2pComponents }; -type WakuOptions = waku.WakuOptions; -type RelayCreateOptions = waku_relay.CreateOptions; - export interface CreateOptions { /** * The PubSub Topic to use. @@ -41,11 +38,11 @@ export interface CreateOptions { */ pubSubTopic?: string; /** - * You can pass options to the `Libp2p` instance used by {@link index.waku.WakuNode} using the {@link CreateOptions.libp2p} property. - * This property is the same type than the one passed to [`Libp2p.create`](https://github.com/libp2p/js-libp2p/blob/master/doc/API.md#create) + * You can pass options to the `Libp2p` instance used by {@link @waku/core.WakuNode} using the {@link CreateOptions.libp2p} property. + * This property is the same type as the one passed to [`Libp2p.create`](https://github.com/libp2p/js-libp2p/blob/master/doc/API.md#create) * apart that we made the `modules` property optional and partial, * allowing its omission and letting Waku set good defaults. - * Notes that some values are overridden by {@link index.waku.WakuNode} to ensure it implements the Waku protocol. + * Notes that some values are overridden by {@link @waku/core.WakuNode} to ensure it implements the Waku protocol. */ libp2p?: Partial; /** diff --git a/packages/dns-discovery/src/index.ts b/packages/dns-discovery/src/index.ts index b54ae2e707..d8bffa326e 100644 --- a/packages/dns-discovery/src/index.ts +++ b/packages/dns-discovery/src/index.ts @@ -11,12 +11,12 @@ import debug from "debug"; import { DnsNodeDiscovery, NodeCapabilityCount } from "./dns.js"; +export { NodeCapabilityCount }; + const log = debug("waku:peer-discovery-dns"); /** * Parse options and expose function to return bootstrap peer addresses. - * - * @throws if an invalid combination of options is passed, see [[BootstrapOptions]] for details. */ export class PeerDiscoveryDns extends EventEmitter diff --git a/packages/peer-exchange/src/index.ts b/packages/peer-exchange/src/index.ts index 198a72769d..4ca6fd7cef 100644 --- a/packages/peer-exchange/src/index.ts +++ b/packages/peer-exchange/src/index.ts @@ -1 +1 @@ -export { wakuPeerExchange, PeerExchangeCodec } from "./waku_peer_exchange.js"; +export * from "./waku_peer_exchange.js"; diff --git a/packages/proto/src/index.ts b/packages/proto/src/index.ts index ca2210ee91..743f9e421d 100644 --- a/packages/proto/src/index.ts +++ b/packages/proto/src/index.ts @@ -2,6 +2,7 @@ export * as proto_message from "./lib/message.js"; export { WakuMessage } from "./lib/filter.js"; export * as proto_topic_only_message from "./lib/topic_only_message.js"; +export { TopicOnlyMessage } from "./lib/topic_only_message.js"; export * as proto_filter from "./lib/filter.js"; diff --git a/typedoc.cjs b/typedoc.cjs new file mode 100644 index 0000000000..2b84c018f0 --- /dev/null +++ b/typedoc.cjs @@ -0,0 +1,16 @@ +const packageJson = require("./package.json"); +// Pop last value out: packages/tests +packageJson.workspaces.pop(); + +module.exports = { + entryPointStrategy: "packages", + entryPoints: packageJson.workspaces, + out: "docs", + exclude: ["**/*.spec.ts"], + excludeInternal: true, + validation: { + invalidLink: true, + notExported: true, + }, +}; +packageJson.workspaces; diff --git a/typedoc.json b/typedoc.json deleted file mode 100644 index 4c614c573f..0000000000 --- a/typedoc.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "entryPointStrategy": "packages", - "entryPoints": [ - "packages/byte-utils", - "packages/core", - "packages/create", - "packages/dns-discovery", - "packages/enr", - "packages/interfaces", - "packages/message-encryption" - ], - "out": "docs", - "exclude": ["**/*.spec.ts"], - "excludeInternal": true, - "validation": { - "invalidLink": true, - "notExported": true - } -}