Add Autogenerated API docs (#5)

* Add Yarn and GitHub workflow config for building docs to GitHub Pages * Add type comments * Address TSDoc warnings * Lint fixes * Revert yarn lock changes --------- Co-authored-by: Antonio Antonino <[email protected]>
KILTprotocol · Jan 30, 2024 · 5c4a7a7 · 5c4a7a7
1 parent 1f2b4b6
commit 5c4a7a7
Show file tree

Hide file tree

Showing 9 changed files with 238 additions and 62 deletions.
diff --git a/.github/workflows/docpublish.yml b/.github/workflows/docpublish.yml
@@ -0,0 +1,24 @@
+name: Build and Deploy API docs
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Install and Build
+        run: |
+          yarn install
+          yarn build:docs
+
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages # The branch the action should deploy to.
+          folder: docs/api # The folder the action should deploy to.
diff --git a/.gitignore b/.gitignore
@@ -22,3 +22,7 @@ cjs
 # VSCode
 
 .vscode
+
+# doc 
+**/docs/api
+/docs/api
diff --git a/.yarn/versions/9db34678.yml b/.yarn/versions/9db34678.yml
@@ -0,0 +1,2 @@
+declined:
+  - "@kiltprotocol/dip-sdk"
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/package.json b/package.json
@@ -21,7 +21,8 @@
     "eslint-plugin-license-header": "^0.6.0",
     "prettier": "^3.0.0",
     "rimraf": "^5.0.1",
-    "typescript": "^5.3.2",
+    "typedoc": "^0.25.7",
+    "typescript": "^5.1",
     "vitest": "^0.33.0"
   },
   "engines": {
@@ -45,9 +46,11 @@
   "scripts": {
     "build": "yarn build:cjs && yarn build:esm",
     "build:cjs": "run -T tsc -p tsconfig.cjs.json && echo '{\"type\": \"commonjs\"}' > ./dist/cjs/package.json",
+    "build:docs": "typedoc --theme default --out docs/api --tsconfig tsconfig.docs.json && touch docs/.nojekyll",
     "build:esm": "run -T tsc -p tsconfig.esm.json && echo '{\"type\": \"module\"}' > ./dist/esm/package.json",
     "check": "tsc -p tsconfig.json",
     "clean": "yarn rimraf -g */{cjs,esm}",
+    "clean:docs": "rimraf docs/api",
     "lint": "eslint --ext .ts . && prettier -c .",
     "lint:fix": "prettier -w . && eslint --fix --ext .ts .",
     "prepublish": "yarn exec cp -f ../../LICENSE .",

diff --git a/src/sibling.ts b/src/sibling.ts
@@ -29,52 +29,52 @@ import type {
 import type { KeyringPair } from "@polkadot/keyring/types"
 import type { Call, Hash } from "@polkadot/types/interfaces"
 
+/** The DIP proof params. */
 export type DipSiblingProofInput = {
+  /** The `Call` on the consumer chain that requires a DIP origin. */
   call: Call
+  /** The `ApiPromise` instance for the consumer chain. */
   consumerApi: ApiPromise
+  /** The DID URI of the DIP subject that is performing the cross-chain operation. */
   didUri: DidUri
+  /** The verification method IDs of the DID to be revealed in the cross-chain operation. */
   keyIds: Array<DidKey["id"]>
+  /** The version of the DIP proof to generate. */
   proofVersion: number
+  /** The `ApiPromise` instance for the provider chain. */
   providerApi: ApiPromise
+  /** The `ApiPromise` instance for the parent relay chain. */
   relayApi: ApiPromise
+  /** The signing callback to sign the cross-chain transaction. */
   signer: SignExtrinsicCallback
+  /** The address of the tx submitter on the consumer chain. */
   submitterAddress: KeyringPair["address"]
+  /** The `VerificationKeyRelationship` required for the DIP operation to be authorized on the relay chain. */
   keyRelationship: VerificationKeyRelationship
-  // Optional, retrieved from chain otherwise
+  /** The block number on the consumer chain to use for the DID signature. If not provided, the latest best block number is used. */
   blockHeight?: BN
+  /** The genesis hash of the consumer chain to use for the DID signature. If not provided, it is retrieved at runtime from the consumer chain. */
   genesisHash?: Hash
+  /** The block number of the provider to use for the generation of the DIP proof. If not provided, the latest finalized block number is used. */
   providerBlockHeight?: BN
-  // With defaults
+  /** The runtime type definition for an `AccountId` on the consumer chain. If not provided, the `AccountId` type is used. */
   accountIdRuntimeType?: string
+  /** The runtime type definition for a `BlockNumber` on the consumer chain. If not provided, the `u64` type is used. */
   blockNumberRuntimeType?: string
+  /** The runtime type definition for the `IdentityDetails` on the consumer chain. If not provided, the `Option<u128>` type, representing a simple nonce, is used. */
   identityDetailsRuntimeType?: string
+  /** Flag indicating whether the generated DIP proof should include the web3name of the DID subject. If not provided, the web3name is not revealed. */
   includeWeb3Name?: boolean
+  /** The list of linked accounts to reveal in the generated DIP proof. If not provided, no account is revealed. */
   linkedAccounts?: readonly PalletDidLookupLinkableAccountLinkableAccountId[]
 }
 
 /**
  * Generate a submittable extrinsic for the provided call which includes a complete DIP proof according to the parameters provided, to be used on a consumer chain of which the provider chain is a sibling.
+ *
  * @param params The DIP proof params.
- * @param params.call The [[Call]] on the consumer chain that requires a DIP origin.
- * @param params.consumerApi The [[ApiPromise]] instance for the consumer chain.
- * @param params.didUri The DID URI of the DIP subject that is performing the cross-chain operation.
- * @param params.keyIds The verification method IDs of the DID to be revealed in the cross-chain operation.
- * @param params.proofVersion The version of the DIP proof to generate.
- * @param params.providerApi The [[ApiPromise]] instance for the provider chain.
- * @param params.relayApi The [[ApiPromise]] instance for the parent relay chain.
- * @param params.signer The signing callback to sign the cross-chain transaction.
- * @param params.submitterAddress The address of the tx submitter on the consumer chain.
- * @param params.keyRelationship The [[VerificationKeyRelationship]] required for the DIP operation to be authorized on the relay chain.
- * @param params.blockHeight [OPTIONAL] The block number on the consumer chain to use for the DID signature. If not provided, the latest best block number is used.
- * @param params.genesisHash [OPTIONAL] The genesis hash of the consumer chain to use for the DID signature. If not provided, it is retrieved at runtime from the consumer chain.
- * @param params.providerBlockHeight [OPTIONAL] The block number of the provider to use for the generation of the DIP proof. If not provided, the latest finalized block number is used.
- * @param params.accountIdRuntimeType [OPTIONAL] The runtime type definition for an `AccountId` on the consumer chain. If not provided, the `AccountId` type is used.
- * @param params.blockNumberRuntimeType [OPTIONAL] The runtime type definition for a `BlockNumber` on the consumer chain. If not provided, the `u64` type is used.
- * @param params.identityDetailsRuntimeType [OPTIONAL] The runtime type definition for the `IdentityDetails` on the consumer chain. If not provided, the `Option<u128>` type, representing a simple nonce, is used.
- * @param params.includeWeb3Name [OPTIONAL] Flag indicating whether the generated DIP proof should include the web3name of the DID subject. If not provided, the web3name is not revealed.
- * @param params.linkedAccounts [OPTIONAL] The list of linked accounts to reveal in the generated DIP proof. If not provided, no account is revealed.
  *
- * @returns The [[SubmittableExtrinsic]] containing the signed cross-chain operation, that must be submitted by the account specified as the `submitterAddress` parameter.
+ * @returns The `SubmittableExtrinsic` containing the signed cross-chain operation, that must be submitted by the account specified as the `submitterAddress` parameter.
  */
 export async function generateDipAuthorizedTxForSibling({
   call,

diff --git a/src/utils.ts b/src/utils.ts
@@ -30,24 +30,32 @@ export const defaultValues = {
   linkedAccounts: [],
 }
 
-type ProviderStateRootProofOpts = {
+/**
+ * The options object provided when generating a Provider state proof.
+ */
+export type ProviderStateRootProofOpts = {
+  /** The `ApiPromise` instance for the provider chain. */
   providerApi: ApiPromise
+  /** The `ApiPromise` instance for the relay chain. */
   relayApi: ApiPromise
-  // Optional
+  /** The block number on the provider chain to use for the state proof. If not provided, the latest finalized block number is used. */
   providerBlockHeight?: BN
 }
-type ProviderStateRootProofRes = {
+/**
+ * The response object containing the provider state root proof.
+ */
+export type ProviderStateRootProofRes = {
+  /** The state proof for the provider header. */
   proof: ReadProof
+  /** The block number of the provider which the proof is anchored to. */
   providerBlockHeight: BN
+  /** The block number of the relaychain which the proof is anchored to. */
   relayBlockHeight: BN
 }
 /**
  * Generate a state proof that proofs the head of the specified parachain.
  *
  * @param params The state proof params.
- * @param params.providerApi The [[ApiPromise]] instance for the provider chain.
- * @param params.relayApi The [[ApiPromise]] instance for the relay chain.
- * @param params.providerBlockHeight [OPTIONAL] The block number on the provider chain to use for the state proof. If not provided, the latest finalized block number is used.
  *
  * @returns The generated state proof.
  */
@@ -92,23 +100,30 @@ export async function generateProviderStateRootProof({
   }
 }
 
-type DipCommitmentProofOpts = {
+/**
+ * The options object provided when generating a DIP commitment proof.
+ */
+export type DipCommitmentProofOpts = {
+  /** The `DidUri` of the subject. */
   didUri: DidUri
+  /** The `ApiPromise` instance for the provider chain. */
   providerApi: ApiPromise
+  /** The block hash on the provider chain to use for the state proof. */
   providerBlockHash: Hash
+  /** The version of the identity commitment to generate the state proof for. */
   version: number
 }
-type DipCommitmentProofRes = {
+/**
+ * The response object for a DIP commitment proof.
+ */
+export type DipCommitmentProofRes = {
+  /** The storage proof for the DIP commitment value. */
   proof: ReadProof
 }
 /**
  * Generate a state proof that proofs the value of an identity commitment on the specified provider chain.
  *
  * @param params The state proof params.
- * @param params.did The [[Did]] of the subject.
- * @param params.providerApi The [[ApiPromise]] instance for the provider chain.
- * @param params.providerBlockHash The block hash on the provider chain to use for the state proof.
- * @param params.version The version of the identity commitment to generate the state proof for.
  *
  * @returns The generated state proof.
  */
@@ -131,31 +146,41 @@ export async function generateDipCommitmentProof({
   return { proof }
 }
 
-type DipIdentityProofOpts = {
+/**
+ * The options object provided when generating a DIP identity proof.
+ */
+export type DipIdentityProofOpts = {
+  /** The `Did` of the subject. */
   didUri: DidUri
+  /** The list of DID verification methods to include in the DIP proof and to reveal to the consumer chain. */
   keyIds: Array<DidKey["id"]>
+  /** A flag indicating whether the web3name should be included in the DIP proof. */
   includeWeb3Name: boolean
+  /** The list of accounts linked to the DID ot include in the DIP proof and to reveal to the consumer chain. */
   linkedAccounts: readonly PalletDidLookupLinkableAccountLinkableAccountId[]
+  /** The `ApiPromise` instance for the provider chain. */
   providerApi: ApiPromise
+  /** The version of the DIP proof to generate. */
   version: number
 }
-type DipIdentityProofRes = {
+/**
+ * The response object for a generated DIP proof.
+ */
+export type DipIdentityProofRes = {
+  /** The generated storage proof. */
   proof: {
+    /** The Merkle proof blinded (not revealed) leaves. */
     blinded: Codec
+    /** The Merkle proof revealed leaves. */
     revealed: Codec
   }
+  /** The Merkle root hash which the proof is anchored to. */
   root: Hash
 }
 /**
  * Generate a DIP proof that reveals the specified information about the DID subject.
  *
  * @param params The DIP proof params.
- * @param params.did The [[Did]] of the subject.
- * @param params.keyIds The list of DID verification methods to include in the DIP proof and to reveal to the consumer chain.
- * @param params.includeWeb3Name A flag indicating whether the web3name should be included in the DIP proof.
- * @param params.linkedAccounts The list of accounts linked to the DID ot include in the DIP proof and to reveal to the consumer chain.
- * @param params.providerApi The [[ApiPromise]] instance for the provider chain.
- * @param params.version The version of the DIP proof to generate.
  *
  * @returns The generated DIP proof.
  */
@@ -187,48 +212,58 @@ export async function generateDipIdentityProof({
   return okProof
 }
 
-type DipDidSignatureProviderOpts = {
+/**
+ * The Provider options object provided when generating a DIP DID signature.
+ */
+export type DipDidSignatureProviderOpts = {
+  /** The `DidUri` of the DIP subject that is performing the cross-chain operation. */
   didUri: DidUri
+  /** The list of `Signers` to use to sign the cross-chain payload. */
   signer: SignExtrinsicCallback
+  /** The `SignatureVerificationRelationship` to use from the provided DID Document to sign the cross-chain payload. */
   keyRelationship: VerificationKeyRelationship
 }
-type DipDidSignatureConsumerOpts = {
+/**
+ * The Consumer options object provided when generating a DIP DID signature.
+ */
+export type DipDidSignatureConsumerOpts = {
+  /** The runtime definition of an `AccountId`. */
   accountIdRuntimeType: string
+  /** The `ApiPromise` instance. */
   api: ApiPromise
+  /** The runtime definition of a `BlockNumber`. */
   blockNumberRuntimeType: string
+  /** The `Call` to DID-authorize. */
   call: Call
+  /** The runtime definition of the `IdentityDetails`. */
   identityDetailsRuntimeType: string
+  /** The address of the submitter account on the consumer chain. */
   submitterAddress: KeyringPair["address"]
-  // Optional
+  /** The block number to use for the DID signature. If not provided, the latest best block number is used. */
   blockHeight?: BN
+  /** The genesis hash to use for the DID signature. If not provided, it is retrieved at runtime. */
   genesisHash?: Hash
 }
-type DipDidSignatureOpts = {
+/**
+ * The options object provided when generating a DIP DID signature.
+ */
+export type DipDidSignatureOpts = {
   consumer: DipDidSignatureConsumerOpts
   provider: DipDidSignatureProviderOpts
 }
-type DipDidSignatureRes = {
+/**
+ * The response object for DIP DID signature.
+ */
+export type DipDidSignatureRes = {
   blockNumber: BN
   signature: Uint8Array
   type: VerificationKeyType
 }
 /**
  * Generate a DID signature to be used in conjunction with a DIP proof to DID-authorize a cross-chain operation.
  *
- * @param params The DID signature parameters.
- * @param params.provider The provider-specific parameters.
- * @param params.provider.didDocument The [[DidDocument] of the DIP subject that is performing the cross-chain operation.
- * @param params.provider.signers The list of [[Signers]] to use to sign the cross-chain payload.
- * @param params.provider.verificationRelationship The [[SignatureVerificationRelationship]] to use from the provided DID Document to sign the cross-chain payload.
- * @param params.consumer The consumer-specific parameters.
- * @param params.consumer.accountIdRuntimeType The runtime definition of an `AccountId`.
- * @param params.consumer.api The [[ApiPromise]] instance.
- * @param params.consumer.blockNumberRuntimeType The runtime definition of a `BlockNumber`.
- * @param params.consumer.call The [[Call]] to DID-authorize.
- * @param params.consumer.identityDetailsRuntimeType The runtime definition of the `IdentityDetails`.
- * @param params.consumer.submitterAddress The address of the submitter account on the consumer chain.
- * @param params.consumer.blockHeight [OPTIONAL] The block number to use for the DID signature. If not provided, the latest best block number is used.
- * @param params.consumer.genesisHash [OPTIONAL] The genesis hash to use for the DID signature. If not provided, it is retrieved at runtime.
+ * @param params The signature generation parameters.
+
  * @returns The generated DIP proof.
  */
 export async function generateDipDidSignature({

diff --git a/tsconfig.docs.json b/tsconfig.docs.json
@@ -0,0 +1,22 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["src/**/*"],
+  "typedocOptions": {
+    "entryPointStrategy": "resolve",
+    "entryPoints": ["src/runtime.ts", "src/sibling.ts", "src/utils.ts"],
+    "out": "docs/api",
+    "theme": "default",
+    "exclude": [
+      "**/*spec.ts",
+      "**/__mocks__/**",
+      "**/tests/**",
+      "**/*.js",
+      "**/node_modules/**"
+    ],
+    "excludeExternals": true,
+    "excludePrivate": true,
+    "hideGenerator": true,
+    "name": "API Documentation",
+    "readme": "README.md"
+  }
+}