Document @solana/compat with TypeDoc (#65)

anza-xyz · Jan 29, 2025 · dedf8b6 · dedf8b6
1 parent 821b80f
commit dedf8b6
Show file tree

Hide file tree

Showing 6 changed files with 55 additions and 7 deletions.
diff --git a/packages/compat/src/address.ts b/packages/compat/src/address.ts
@@ -2,9 +2,16 @@ import { Address } from '@solana/addresses';
 import { PublicKey } from '@solana/web3.js';
 
 /**
- * Convert from a Legacy Web3 JS PublicKey to a base58 encoded address
- * @param publicKey The PublicKey to convert
- * @returns         An Address
+ * Converts a legacy [PublicKey](https://solana-labs.github.io/solana-web3.js/classes/PublicKey.html)
+ * object to an {@link Address}.
+ *
+ * @example
+ * ```ts
+ * import { fromLegacyPublicKey } from '@solana/compat';
+ *
+ * const legacyPublicKey = new PublicKey('49XBVQsvSW44ULKL9qufS9YqQPbdcps1TQRijx4FQ9sH');
+ * const address = fromLegacyPublicKey(legacyPublicKey);
+ * ```
  */
 export function fromLegacyPublicKey<TAddress extends string>(publicKey: PublicKey): Address<TAddress> {
     return publicKey.toBase58() as Address<TAddress>;

diff --git a/packages/compat/src/index.ts b/packages/compat/src/index.ts
@@ -1,3 +1,10 @@
+/**
+ * This package contains utilities for converting from legacy web3.js classes to the new data
+ * structures. It can be used standalone, but it is also exported as part of the Solana JavaScript
+ * SDK [`@solana/web3.js@next`](https://github.com/anza-xyz/solana-web3.js/tree/main/packages/library).
+ *
+ * @packageDocumentation
+ */
 export * from './address';
 export * from './instruction';
 export * from './keypair';

diff --git a/packages/compat/src/instruction.ts b/packages/compat/src/instruction.ts
@@ -3,6 +3,19 @@ import { TransactionInstruction } from '@solana/web3.js';
 
 import { fromLegacyPublicKey } from './address';
 
+/**
+ * This can be used to convert a legacy [`TransactionInstruction`](https://solana-labs.github.io/solana-web3.js/classes/TransactionInstruction.html)
+ * object to an {@link IInstruction}.
+ *
+ * @example
+ * ```ts
+ * import { fromLegacyTransactionInstruction } from '@solana/compat';
+ *
+ * // Imagine a function that returns a legacy `TransactionInstruction`
+ * const legacyInstruction = getMyLegacyInstruction();
+ * const instruction = fromLegacyTransactionInstruction(legacyInstruction);
+ * ```
+ */
 export function fromLegacyTransactionInstruction(legacyInstruction: TransactionInstruction): IInstruction {
     const data = legacyInstruction.data?.byteLength > 0 ? Uint8Array.from(legacyInstruction.data) : undefined;
     const accounts = legacyInstruction.keys.map(accountMeta =>

diff --git a/packages/compat/src/keypair.ts b/packages/compat/src/keypair.ts
@@ -2,9 +2,16 @@ import { createKeyPairFromBytes } from '@solana/keys';
 import { Keypair } from '@solana/web3.js';
 
 /**
- * Convert from a Legacy Web3 JS Keypair to a CryptoKeyPair
- * @param keypair   The Keypair to convert
- * @returns         A CryptoKeyPair
+ * Converts a legacy [Keypair](https://solana-labs.github.io/solana-web3.js/classes/Keypair.html)
+ * object to a native Ed25519 {@link CryptoKeyPair} object.
+ *
+ * @example
+ * ```ts
+ * import { fromLegacyKeypair } from '@solana/compat';
+ *
+ * const legacyKeyPair = Keypair.generate();
+ * const { privateKey, publicKey } = await fromLegacyKeypair(legacyKeyPair);
+ * ```
  */
 export async function fromLegacyKeypair(keypair: Keypair, extractable?: boolean): Promise<CryptoKeyPair> {
     const bytes = new Uint8Array(64);

diff --git a/packages/compat/src/transaction.ts b/packages/compat/src/transaction.ts
@@ -18,6 +18,19 @@ function convertSignatures(transaction: VersionedTransaction, staticAccountKeys:
     );
 }
 
+/**
+ * This can be used to convert a legacy [VersionedTransaction](https://solana-labs.github.io/solana-web3.js/classes/VersionedTransaction.html)
+ * object to a {@link Transaction}.
+ *
+ * @example
+ * ```ts
+ * import { fromVersionedTransaction } from '@solana/compat';
+ *
+ * // Imagine a function that returns a legacy `VersionedTransaction`
+ * const legacyVersionedTransaction = getMyLegacyVersionedTransaction();
+ * const transaction = fromVersionedTransaction(legacyVersionedTransaction);
+ * ```
+ */
 export function fromVersionedTransaction(transaction: VersionedTransaction): Transaction {
     const { message } = transaction;
     const { staticAccountKeys } = message.getAccountKeys();

diff --git a/packages/compat/typedoc.json b/packages/compat/typedoc.json
@@ -1,5 +1,6 @@
 {
     "$schema": "https://typedoc.org/schema.json",
     "extends": ["../typedoc.base.json"],
-    "entryPoints": ["src/index.ts"]
+    "entryPoints": ["src/index.ts"],
+    "readme": "none"
 }