fix: update tsdoc comments to expose internal methods (#1761)

* refactor: update internal markings * refactor: update tsdocs --------- Co-authored-by: janniks <[email protected]>
hirosystems · Nov 14, 2024 · 2f2b12b · 2f2b12b
1 parent acf93b6
commit 2f2b12b
Show file tree

Hide file tree

Showing 6 changed files with 8 additions and 30 deletions.
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/common/src/fetch.ts b/packages/common/src/fetch.ts
@@ -36,7 +36,7 @@ export const setFetchOptions = (ops: RequestInit): RequestInit => {
   return Object.assign(defaultFetchOpts, ops);
 };
 
-/** @internal */
+/** @ignore */
 export async function fetchWrapper(input: RequestInfo, init?: RequestInit): Promise<Response> {
   const fetchOpts = {};
   // Use the provided options in request options along with default or user provided values
@@ -94,7 +94,7 @@ export interface ApiKeyMiddlewareOpts {
   apiKey: string;
 }
 
-/** @internal */
+/** @ignore */
 export function hostMatches(host: string, pattern: string | RegExp) {
   if (typeof pattern === 'string') return pattern === host;
   return pattern.exec(host);

diff --git a/packages/transactions/src/authorization.ts b/packages/transactions/src/authorization.ts
@@ -170,19 +170,21 @@ export function createMultiSigSpendingCondition(
   };
 }
 
-/** @internal */
+/** Advanced: Checks if the condition is a single signature spending condition. */
 export function isSingleSig(
   condition: SpendingConditionOpts
 ): condition is SingleSigSpendingConditionOpts {
   return 'signature' in condition;
 }
 
-/** @internal */
+// todo: add override for the functions below to allow for address string input as well.
+
+/** Advanced: Checks if the address is for a sequential (legacy) multi-signature spending condition. */
 export function isSequentialMultiSig(hashMode: AddressHashMode): boolean {
   return hashMode === AddressHashMode.P2SH || hashMode === AddressHashMode.P2WSH;
 }
 
-/** @internal */
+/** Advanced: Checks if the address is for a non-sequential multi-signature spending condition. */
 export function isNonSequentialMultiSig(hashMode: AddressHashMode): boolean {
   return (
     hashMode === AddressHashMode.P2SHNonSequential ||
@@ -214,7 +216,6 @@ export function serializeSingleSigSpendingCondition(
   return bytesToHex(serializeSingleSigSpendingConditionBytes(condition));
 }
 
-/** @internal */
 export function serializeSingleSigSpendingConditionBytes(
   condition: SingleSigSpendingConditionOpts
 ): Uint8Array {
@@ -235,7 +236,6 @@ export function serializeMultiSigSpendingCondition(
   return bytesToHex(serializeMultiSigSpendingConditionBytes(condition));
 }
 
-/** @internal */
 export function serializeMultiSigSpendingConditionBytes(
   condition: MultiSigSpendingConditionOpts
 ): Uint8Array {
@@ -338,7 +338,6 @@ export function serializeSpendingCondition(condition: SpendingConditionOpts): st
   return bytesToHex(serializeSpendingConditionBytes(condition));
 }
 
-/** @internal */
 export function serializeSpendingConditionBytes(condition: SpendingConditionOpts): Uint8Array {
   if (isSingleSig(condition)) return serializeSingleSigSpendingConditionBytes(condition);
   return serializeMultiSigSpendingConditionBytes(condition);
@@ -695,7 +694,6 @@ export function serializeAuthorization(auth: Authorization): string {
   return bytesToHex(serializeAuthorizationBytes(auth));
 }
 
-/** @internal */
 export function serializeAuthorizationBytes(auth: Authorization): Uint8Array {
   const bytesArray = [];
   bytesArray.push(auth.authType);

diff --git a/packages/transactions/src/utils.ts b/packages/transactions/src/utils.ts
@@ -196,7 +196,7 @@ export const validateStacksAddress = (address: string): boolean => {
   }
 };
 
-/** @internal */
+/** @ignore */
 export function parseContractId(contractId: ContractIdString) {
   const [address, name] = contractId.split('.');
   if (!address || !name) throw new Error(`Invalid contract identifier: ${contractId}`);

diff --git a/packages/transactions/src/wire/serialization.ts b/packages/transactions/src/wire/serialization.ts
@@ -75,11 +75,9 @@ import {
   TransactionAuthFieldWire,
 } from './types';
 
-/** @internal */
 export function serializeStacksWire(wire: StacksWire): string {
   return bytesToHex(serializeStacksWireBytes(wire));
 }
-/** @internal */
 export function serializeStacksWireBytes(wire: StacksWire): Uint8Array {
   switch (wire.type) {
     case StacksWireType.Address:
@@ -107,7 +105,6 @@ export function serializeStacksWireBytes(wire: StacksWire): Uint8Array {
   }
 }
 
-/** @internal */
 export function deserializeStacksWire(
   bytesReader: string | Uint8Array | BytesReader,
   type: StacksWireType,
@@ -145,15 +142,13 @@ export function deserializeStacksWire(
 export function serializeAddress(address: AddressWire): string {
   return bytesToHex(serializeAddressBytes(address));
 }
-/** @internal */
 export function serializeAddressBytes(address: AddressWire): Uint8Array {
   const bytesArray = [];
   bytesArray.push(hexToBytes(intToHex(address.version, 1)));
   bytesArray.push(hexToBytes(address.hash160));
   return concatArray(bytesArray);
 }
 
-/** @internal */
 export function deserializeAddress(serialized: string | Uint8Array | BytesReader): AddressWire {
   const bytesReader = isInstance(serialized, BytesReader)
     ? serialized
@@ -167,7 +162,6 @@ export function deserializeAddress(serialized: string | Uint8Array | BytesReader
 export function serializePrincipal(principal: PostConditionPrincipalWire): string {
   return bytesToHex(serializePrincipalBytes(principal));
 }
-/** @internal */
 export function serializePrincipalBytes(principal: PostConditionPrincipalWire): Uint8Array {
   const bytesArray = [];
   bytesArray.push(principal.prefix);
@@ -183,7 +177,6 @@ export function serializePrincipalBytes(principal: PostConditionPrincipalWire):
   return concatArray(bytesArray);
 }
 
-/** @internal */
 export function deserializePrincipal(
   serialized: string | Uint8Array | BytesReader
 ): PostConditionPrincipalWire {
@@ -212,7 +205,6 @@ export function deserializePrincipal(
 export function serializeLPString(lps: LengthPrefixedStringWire): string {
   return bytesToHex(serializeLPStringBytes(lps));
 }
-/** @internal */
 export function serializeLPStringBytes(lps: LengthPrefixedStringWire): Uint8Array {
   const bytesArray = [];
   const contentBytes = utf8ToBytes(lps.content);
@@ -222,7 +214,6 @@ export function serializeLPStringBytes(lps: LengthPrefixedStringWire): Uint8Arra
   return concatArray(bytesArray);
 }
 
-/** @internal */
 export function deserializeLPString(
   serialized: string | Uint8Array | BytesReader,
   prefixBytes?: number,
@@ -240,7 +231,6 @@ export function deserializeLPString(
 export function serializeMemoString(memoString: MemoStringWire): string {
   return bytesToHex(serializeMemoStringBytes(memoString));
 }
-/** @internal */
 export function serializeMemoStringBytes(memoString: MemoStringWire): Uint8Array {
   const bytesArray = [];
   const contentBytes = utf8ToBytes(memoString.content);
@@ -249,7 +239,6 @@ export function serializeMemoStringBytes(memoString: MemoStringWire): Uint8Array
   return concatArray(bytesArray);
 }
 
-/** @internal */
 export function deserializeMemoString(
   serialized: string | Uint8Array | BytesReader
 ): MemoStringWire {
@@ -264,7 +253,6 @@ export function deserializeMemoString(
 export function serializeAsset(info: AssetWire): string {
   return bytesToHex(serializeAssetBytes(info));
 }
-/** @internal */
 export function serializeAssetBytes(info: AssetWire): Uint8Array {
   const bytesArray = [];
   bytesArray.push(serializeAddressBytes(info.address));
@@ -273,7 +261,6 @@ export function serializeAssetBytes(info: AssetWire): Uint8Array {
   return concatArray(bytesArray);
 }
 
-/** @internal */
 export function deserializeAsset(serialized: string | Uint8Array | BytesReader): AssetWire {
   const bytesReader = isInstance(serialized, BytesReader)
     ? serialized
@@ -289,7 +276,6 @@ export function deserializeAsset(serialized: string | Uint8Array | BytesReader):
 export function serializeLPList(lpList: LengthPrefixedList): string {
   return bytesToHex(serializeLPListBytes(lpList));
 }
-/** @internal */
 export function serializeLPListBytes(lpList: LengthPrefixedList): Uint8Array {
   const list = lpList.values;
   const bytesArray = [];
@@ -300,7 +286,6 @@ export function serializeLPListBytes(lpList: LengthPrefixedList): Uint8Array {
   return concatArray(bytesArray);
 }
 
-/** @internal */
 export function deserializeLPList(
   serialized: string | Uint8Array | BytesReader,
   type: StacksWireType,
@@ -345,7 +330,6 @@ export function serializePostConditionWire(postCondition: PostConditionWire): st
   return bytesToHex(serializePostConditionWireBytes(postCondition));
 }
 
-/** @internal */
 export function serializePostConditionWireBytes(postCondition: PostConditionWire): Uint8Array {
   const bytesArray = [];
   bytesArray.push(postCondition.conditionType);
@@ -377,7 +361,6 @@ export function serializePostConditionWireBytes(postCondition: PostConditionWire
   return concatArray(bytesArray);
 }
 
-/** @internal */
 export function deserializePostConditionWire(
   serialized: string | Uint8Array | BytesReader
 ): PostConditionWire {

diff --git a/packages/transactions/src/wire/types.ts b/packages/transactions/src/wire/types.ts
@@ -38,7 +38,6 @@ export function whenWireType(wireType: StacksWireType) {
   return <T>(wireTypeMap: WhenWireTypeMap<T>): T => wireTypeMap[wireType];
 }
 
-/** @internal */
 export type StacksWire =
   | AddressWire
   | PostConditionPrincipalWire