fix: add clarity typedoc annotations

packages/transactions/src/clarity/deserialize.ts

@@ -21,6 +21,28 @@ import { deserializeAddress, deserializeLPString } from '../types';
 import { DeserializationError } from '../errors';
 import { stringAsciiCV, stringUtf8CV } from './types/stringCV';
 
+/**
+ * Deserializes clarity value to clarity type
+ *
+ * @param {value} Buffer | string value to be converted to clarity type
+ **
+ * @returns {ClarityType} returns the clarity type instance
+ *
+ * @example
+ * ```typescript
+ *  import { intCV, serializeCV, deserializeCV } from '@stacks/transactions';
+ *
+ *  const serialized = serializeCV(intCV(100)); // Similarly works for other clarity types as well like listCV, booleanCV ...
+ *
+ *  // <Buffer 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 64>
+ *
+ *  const deserialized = deserializeCV(serialized);
+ *  // { type: 0, value: 100n }
+ * ```
+ *
+ * @visit
+ * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples}
+ */
 export default function deserializeCV<T extends ClarityValue = ClarityValue>(
   serializedClarityValue: BufferReader | Buffer | string
 ): T {

packages/transactions/src/clarity/serialize.ts

@@ -128,6 +128,25 @@ function serializeStringUtf8CV(cv: StringUtf8CV) {
   return serializeStringCV(cv, 'utf8');
 }
 
+/**
+ * Serializes clarity value to buffer
+ *
+ * @param {value} clarity value to be converted to buffer
+ **
+ * @returns {Buffer} returns the buffer instance
+ *
+ * @example
+ * ```typescript
+ *  import { intCV, serializeCV } from '@stacks/transactions';
+ *
+ *  const serialized = serializeCV(intCV(100)); // Similarly works for other clarity types as well like listCV, booleanCV ...
+ *
+ *  // <Buffer 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 64>
+ * ```
+ *
+ * @visit
+ * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples}
+ */
 export function serializeCV(value: ClarityValue): Buffer {
   switch (value.type) {
     case ClarityType.BoolTrue:

packages/transactions/src/clarity/types/booleanCV.ts

@@ -10,7 +10,40 @@ interface FalseCV {
   type: ClarityType.BoolFalse;
 }
 
+/**
+ * Converts true to BooleanCV clarity type
+ *
+ * @returns {BooleanCV} returns instance of type BooleanCV
+ *
+ * @example
+ * ```typescript
+ *  import { trueCV } from '@stacks/transactions';
+ *
+ *  const trueCV = trueCV();
+ *  // { type: 3 }
+ * ```
+ *
+ * @visit
+ * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples}
+ */
 const trueCV = (): BooleanCV => ({ type: ClarityType.BoolTrue });
+
+/**
+ * Converts false to BooleanCV clarity type
+ *
+ * @returns {BooleanCV} returns instance of type BooleanCV
+ *
+ * @example
+ * ```typescript
+ *  import { falseCV } from '@stacks/transactions';
+ *
+ *  const falseCV = falseCV();
+ *  // { type: 4 }
+ * ```
+ *
+ * @visit
+ * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples}
+ */
 const falseCV = (): BooleanCV => ({ type: ClarityType.BoolFalse });
 
 export { BooleanCV, TrueCV, FalseCV, trueCV, falseCV };

packages/transactions/src/clarity/types/bufferCV.ts

@@ -6,6 +6,27 @@ interface BufferCV {
   readonly buffer: Buffer;
 }
 
+/**
+ * Converts a buffer to BufferCV clarity type
+ *
+ * @param {buffer} buffer value to be converted to clarity type
+ *
+ * @returns {BufferCV} returns instance of type BufferCV
+ *
+ * @example
+ * ```typescript
+ *  import { bufferCV } from '@stacks/transactions';
+ *
+ *  const buffer = Buffer.from('this is a test');
+ *  const buf = bufferCV(buffer);
+ *  // { type: 2, buffer: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74> }
+ *  const value = buf.buffer.toString();
+ *  // this is a test
+ * ```
+ *
+ * @visit
+ * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples}
+ */
 const bufferCV = (buffer: Buffer): BufferCV => {
   if (buffer.length > 1000000) {
     throw new Error('Cannot construct clarity buffer that is greater than 1MB');
@@ -14,6 +35,27 @@ const bufferCV = (buffer: Buffer): BufferCV => {
   return { type: ClarityType.Buffer, buffer };
 };
 
+/**
+ * Converts a string to BufferCV clarity type
+ *
+ * @param {str} string input to be converted to bufferCV clarity type
+ *
+ * @returns {BufferCV} returns instance of type BufferCV
+ *
+ * @example
+ * ```typescript
+ *  import { bufferCVFromString } from '@stacks/transactions';
+ *
+ *  const str = 'this is a test';
+ *  const buf = bufferCVFromString(str);
+ *  // { type: 2, buffer: <Buffer 74 68 69 73 20 69 73 20 61 20 74 65 73 74> }
+ *  const value = buf.buffer.toString();
+ *  // this is a test
+ *```
+ *
+ * @visit
+ * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples}
+ */
 const bufferCVFromString = (str: string): BufferCV => bufferCV(Buffer.from(str));
 
 export { BufferCV, bufferCV, bufferCVFromString };

packages/transactions/src/clarity/types/intCV.ts

@@ -12,6 +12,24 @@ interface IntCV {
   readonly value: bigint;
 }
 
+/**
+ * Converts IntegerType in to IntCV clarity type
+ *
+ * @param {value} integer value to be converted to IntCV clarity type
+ *
+ * @returns {IntCV} returns instance of type IntCV
+ *
+ * @example
+ * ```typescript
+ *  import { intCV } from '@stacks/transactions';
+ *
+ *  const value = intCV('100'); // parameter any of type: number | string | bigint | Uint8Array | BN
+ *  // { type: 0, value: 100n }
+ * ```
+ *
+ * @visit
+ * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples}
+ */
 const intCV = (value: IntegerType): IntCV => {
   const bigInt = intToBigInt(value, true);
   if (bigInt > MAX_I128) {
@@ -31,6 +49,24 @@ interface UIntCV {
   readonly value: bigint;
 }
 
+/**
+ * Converts IntegerType in to IntCV clarity type
+ *
+ * @param {value} integer value to be converted to UIntCV clarity type (Only unsigned integer is allowed otherwise throws exception)
+ *
+ * @returns {UIntCV} returns instance of type UIntCV
+ *
+ * @example
+ * ```typescript
+ *  import { uintCV } from '@stacks/transactions';
+ *
+ *  const value = uintCV('100'); // parameter any of type: number | string | bigint | Uint8Array | BN
+ *  // { type: 1, value: 100n }
+ * ```
+ *
+ * @visit
+ * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples}
+ */
 const uintCV = (value: IntegerType): UIntCV => {
   const bigInt = intToBigInt(value, false);
   if (bigInt < MIN_U128) {

packages/transactions/src/clarity/types/listCV.ts

@@ -6,6 +6,24 @@ interface ListCV<T extends ClarityValue = ClarityValue> {
   list: T[];
 }
 
+/**
+ * Create list of clarity types
+ *
+ * @param {ClarityValue>values: T[]} list of  ClarityValues to be converted to ListCV clarity type
+ *
+ * @returns {ListCV<T>} returns instance of type ListCV<T>
+ *
+ * @example
+ * ```typescript
+ *  import { listCV, intCV } from '@stacks/transactions';
+ *
+ *  const list = listCV([intCV(1), intCV(2), intCV(3), intCV(-4)]);
+ *  // { type: 11, list: [ { type: 0, value: 1n }, { type: 0, value: 2n }, { type: 0, value: 3n }, { type: 0, value: -4n } ] }
+ * ```
+ *
+ * @visit
+ * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples}
+ */
 function listCV<T extends ClarityValue = ClarityValue>(values: T[]): ListCV<T> {
   return { type: ClarityType.List, list: values };
 }

packages/transactions/src/clarity/types/optionalCV.ts

@@ -11,10 +11,44 @@ interface SomeCV<T extends ClarityValue = ClarityValue> {
   readonly value: T;
 }
 
+/**
+ * Create a null clarity type
+ **
+ * @returns {NoneCV} returns instance of type NoneCV
+ *
+ * @example
+ * ```typescript
+ *  import { noneCV } from '@stacks/transactions';
+ *
+ *  const value = noneCV();
+ *  // { type: 9 }
+ * ```
+ *
+ * @visit
+ * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples}
+ */
 function noneCV(): NoneCV {
   return { type: ClarityType.OptionalNone };
 }
 
+/**
+ * Converts any ClarityValue in to OptionalCV clarity type
+ *
+ * @param {ClarityValue} value to be converted to OptionalCV clarity type
+ *
+ * @returns {OptionalCV} returns instance of type OptionalCV
+ *
+ * @example
+ * ```typescript
+ *  import { someCV, trueCV } from '@stacks/transactions';
+ *
+ *  const value = someCV(trueCV());
+ *  // { type: 10, value: { type: 3 } }
+ * ```
+ *
+ * @visit
+ * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples}
+ */
 function someCV<T extends ClarityValue = ClarityValue>(value: T): OptionalCV<T> {
   return { type: ClarityType.OptionalSome, value };
 }

packages/transactions/src/clarity/types/principalCV.ts

@@ -36,21 +36,104 @@ function principalCV(principal: string): PrincipalCV {
   }
 }
 
+/**
+ * Converts stx address in to StandardPrincipalCV clarity type
+ *
+ * @param {addressString} string value to be converted to StandardPrincipalCV clarity type
+ *
+ * @returns {StandardPrincipalCV} returns instance of type StandardPrincipalCV
+ *
+ * @example
+ * ```typescript
+ *  import { standardPrincipalCV } from '@stacks/transactions';
+ *
+ *  const addr = standardPrincipalCV('SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B');
+ *  // { type: 5, address: { type: 0, version: 22, hash160: 'a5d9d331000f5b79578ce56bd157f29a9056f0d6' } }
+ * ```
+ *
+ * @visit
+ * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples}
+ */
 function standardPrincipalCV(addressString: string): StandardPrincipalCV {
   const addr = createAddress(addressString);
   return { type: ClarityType.PrincipalStandard, address: addr };
 }
 
+/**
+ * Converts stx address in to StandardPrincipalCV clarity type
+ *
+ * @param {addressString} string value to be converted to StandardPrincipalCV clarity type
+ *
+ * @returns {StandardPrincipalCV} returns instance of type StandardPrincipalCV
+ *
+ * @example
+ * ```typescript
+ *  import { standardPrincipalCVFromAddress, Address  } from '@stacks/transactions';
+ *
+ *  const address: Address = {
+ *    type: 0,
+ *    version: 22,
+ *    hash160: 'a5d9d331000f5b79578ce56bd157f29a9056f0d6'
+ *  };
+ *
+ *  const principalCV = standardPrincipalCVFromAddress(address);
+ *  // { type: 5, address: { type: 0, version: 22, hash160: 'a5d9d331000f5b79578ce56bd157f29a9056f0d6' } }
+ * ```
+ *
+ * @visit
+ * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples}
+ */
 function standardPrincipalCVFromAddress(address: Address): StandardPrincipalCV {
   return { type: ClarityType.PrincipalStandard, address };
 }
 
+/**
+ * Converts stx address in to ContractPrincipalCV clarity type
+ *
+ * @param {addressString} string value to be converted to ContractPrincipalCV clarity type
+
+ * @param {contractName} string containing contract name
+ *
+ * @returns {ContractPrincipalCV} returns instance of type ContractPrincipalCV
+ *
+ * @example
+ * ```typescript
+ *  import { contractPrincipalCV } from '@stacks/transactions';
+ *
+ *  const contractAddress = contractPrincipalCV('SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B', 'test');
+ *  // { type: 6, address: { type: 0, version: 22, hash160: 'a5d9d331000f5b79578ce56bd157f29a9056f0d6' }, contractName: { type: 2, content: 'test', lengthPrefixBytes: 1, maxLengthBytes: 128 } }
+ * ```
+ *
+ * @visit
+ * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples}
+ */
 function contractPrincipalCV(addressString: string, contractName: string): ContractPrincipalCV {
   const addr = createAddress(addressString);
   const lengthPrefixedContractName = createLPString(contractName);
   return contractPrincipalCVFromAddress(addr, lengthPrefixedContractName);
 }
 
+/**
+ * Create ContractPrincipalCV from Address type
+ *
+ * @param {address} address value to be converted to ContractPrincipalCV clarity type
+ *
+ * @param {contractName} contract name of type LengthPrefixedString
+ *
+ * @returns {ContractPrincipalCV} returns instance of type ContractPrincipalCV
+ *
+ * @example
+ * ```typescript
+ *  import { contractPrincipalCVFromAddress, createLPString, createAddress } from '@stacks/transactions';
+ *
+ *  const contractAddressCV = contractPrincipalCVFromAddress(createAddress('SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B'), createLPString('test'));
+ *
+ *  // { type: 6, address: { type: 0, version: 22, hash160: 'a5d9d331000f5b79578ce56bd157f29a9056f0d6' }, contractName: { type: 2, content: 'test', lengthPrefixBytes: 1, maxLengthBytes: 128 } }
+ * ```
+ *
+ * @visit
+ * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples}
+ */
 function contractPrincipalCVFromAddress(
   address: Address,
   contractName: LengthPrefixedString