Allow specifying docs in addPdasVisitor (#778)

.changeset/forty-oranges-serve.md

@@ -0,0 +1,5 @@
+---
+'@codama/renderers-js': patch
+---
+
+Add docs to PDA derivation functions

.changeset/old-cats-fall.md

@@ -0,0 +1,5 @@
+---
+'@codama/visitors': patch
+---
+
+Allow specifying docs for PDA nodes in addPdasVisitor

packages/renderers-js/e2e/token/idl.json

@@ -2260,6 +2260,7 @@
         {
           "kind": "pdaNode",
           "name": "associatedToken",
+          "docs": ["The address of the associated token account."],
           "seeds": [
             {
               "kind": "variablePdaSeedNode",

packages/renderers-js/e2e/token/src/generated/pdas/associatedToken.ts

@@ -22,6 +22,7 @@ export type AssociatedTokenSeeds = {
   mint: Address;
 };
 
+/** The address of the associated token account. */
 export async function findAssociatedTokenPda(
   seeds: AssociatedTokenSeeds,
   config: { programAddress?: Address | undefined } = {}

packages/renderers-js/public/templates/fragments/pdaFunction.njk

@@ -11,6 +11,7 @@ export type {{ pdaSeedsType }} = {
 }
 {% endif %}
 
+{{ macros.docblock(pdaDocs) }}
 export async function {{ findPdaFunction }}(
   {% if hasVariableSeeds %}
     seeds: {{ pdaSeedsType }},

packages/renderers-js/src/fragments/pdaFunction.ts

@@ -37,6 +37,7 @@ export function getPdaFunctionFragment(
     return fragmentFromTemplate('pdaFunction.njk', {
         findPdaFunction: nameApi.pdaFindFunction(pdaNode.name),
         hasVariableSeeds,
+        pdaDocs: pdaNode.docs,
         pdaSeedsType: nameApi.pdaSeedsType(pdaNode.name),
         programAddress: pdaNode.programId ?? programNode.publicKey,
         seeds,

packages/visitors/src/addPdasVisitor.ts

@@ -1,8 +1,8 @@
 import { CODAMA_ERROR__VISITORS__CANNOT_ADD_DUPLICATED_PDA_NAMES, CodamaError } from '@codama/errors';
-import { assertIsNode, camelCase, pdaNode, PdaSeedNode, programNode } from '@codama/nodes';
+import { assertIsNode, camelCase, pdaNode, PdaNodeInput, programNode } from '@codama/nodes';
 import { bottomUpTransformerVisitor } from '@codama/visitors-core';
 
-export function addPdasVisitor(pdas: Record<string, { name: string; seeds: PdaSeedNode[] }[]>) {
+export function addPdasVisitor(pdas: Record<string, Omit<PdaNodeInput, 'programId'>[]>) {
     return bottomUpTransformerVisitor(
         Object.entries(pdas).map(([uncasedProgramName, newPdas]) => {
             const programName = camelCase(uncasedProgramName);
@@ -22,7 +22,7 @@ export function addPdasVisitor(pdas: Record<string, { name: string; seeds: PdaSe
                     }
                     return programNode({
                         ...node,
-                        pdas: [...node.pdas, ...newPdas.map(pda => pdaNode({ name: pda.name, seeds: pda.seeds }))],
+                        pdas: [...node.pdas, ...newPdas.map(({ name, seeds, docs }) => pdaNode({ docs, name, seeds }))],
                     });
                 },
             };

packages/visitors/test/addPdasVisitor.test.ts

@@ -99,3 +99,48 @@ test('it fails to add a PDA if its name conflicts with an existing PDA on the pr
         }),
     );
 });
+
+test('it adds PDA nodes to a program with docs', () => {
+    // Given a program with a single PDA.
+    const node = programNode({
+        name: 'myProgram',
+        pdas: [
+            pdaNode({
+                name: 'associatedToken',
+                seeds: [
+                    variablePdaSeedNode('owner', publicKeyTypeNode()),
+                    constantPdaSeedNodeFromProgramId(),
+                    variablePdaSeedNode('mint', publicKeyTypeNode()),
+                ],
+            }),
+        ],
+        publicKey: 'Epo9rxh99jpeeWabRZi4tpgUVxZQeVn9vbbDjUztJtu4',
+    });
+
+    // When we add two more PDAs.
+    const newPdas = [
+        pdaNode({
+            docs: 'Metadata for a token.',
+            name: 'metadata',
+            seeds: [
+                constantPdaSeedNodeFromString('utf8', 'metadata'),
+                constantPdaSeedNodeFromProgramId(),
+                variablePdaSeedNode('mint', publicKeyTypeNode()),
+            ],
+        }),
+        pdaNode({
+            docs: 'The master edition.',
+            name: 'masterEdition',
+            seeds: [
+                constantPdaSeedNodeFromString('utf8', 'metadata'),
+                constantPdaSeedNodeFromProgramId(),
+                variablePdaSeedNode('mint', publicKeyTypeNode()),
+                constantPdaSeedNodeFromString('utf8', 'edition'),
+            ],
+        }),
+    ];
+    const result = visit(node, addPdasVisitor({ myProgram: newPdas }));
+
+    // Then we expect the following program to be returned.
+    expect(result).toEqual({ ...node, pdas: [...node.pdas, ...newPdas] });
+});