improve inline docs

[jinglescode]

AI readiness and developer clarity, your inline docs should include:

• A clear description of what the function/class/module does, including its purpose and context.
• Parameter documentation with types, constraints, and example values.
• Return value documentation with type and shape of the result, and example values.
• Usage examples, both minimal and full code examples.
• Example inputs and expected outputs, so AI and humans can understand end-to-end usage.
• Error conditions and edge cases, including what gets thrown or returned on failure.

inline doc template for functions:

/**
 * @function [FunctionName]
 * @description
 * Short and clear one-line summary of what this function does.
 * Mention the Cardano-specific context if relevant.
 *
 * @purpose
 * Explain why a developer would use this, what problem it solves, and when it should be used.
 *
 * @param {<Type>} paramName - Description of this parameter, including:
 *   - Purpose
 *   - Constraints (e.g., must be non-empty, valid Bech32 address, etc.)
 *   - Example value: `addr1qxy...`
 *
 * @param {<Type>} anotherParamName - Description...
 *
 * @returns {<Type>} Description of the return value:
 *   - Shape of the object or primitive
 *   - Key fields and their meaning
 *   - Example value or structure
 *
 * @throws {<ErrorType>} When this error is thrown and why
 * @throws {<AnotherErrorType>} Another possible error
 *
 * @example
 * // Minimal usage
 * const result = mesh.functionName("inputValue");
 *
 * @see mesh.relatedFunction
 * @see https://meshjs.dev/docs/path/to/doc
 */

• @function: clearly labels the entity for linting & doc generation.
• @description / @purpose: split so AI & humans see what it does vs why it’s used.
• @param: includes type, purpose, constraints, and example value.
• @returns: includes type and example output.
• @throws: lists errors for better developer & AI safety.
• @example: ensures we have explicit input/output mapping.
• @see: links to related functions or docs for context.

example: txIn

/**
 * @function txIn
 * @description
 * Sets an input UTxO for the transaction being built.
 * Can handle both PubKey and Plutus script inputs depending on builder state.
 *
 * @purpose
 * Used when specifying which UTxO(s) should be consumed as inputs in a transaction.
 * Supports optional asset amounts, addresses, and reference script sizes for offline building.
 *
 * @param {string} txHash
 *   The transaction hash of the input UTxO.
 *   - Must be a valid 64-character hex string.
 *   - Example: `"9f3a2b...c8d4"`.
 *
 * @param {number} txIndex
 *   The transaction index of the input UTxO within the transaction’s outputs.
 *   - Must be a non-negative integer.
 *   - Example: `0`.
 *
 * @param {Asset[]} [amount]
 *   (Optional) Array of asset objects representing the value at the UTxO.
 *   - Each asset must have a `unit` and `quantity`.
 *   - Example: `[{ unit: "lovelace", quantity: "5000000" }]`.
 *
 * @param {string} [address]
 *   (Optional) The Bech32 address of the input UTxO.
 *   - Must be a valid Cardano address.
 *   - Example: `"addr1qxy..."`.
 *
 * @param {number} [scriptSize]
 *   (Optional) Size in bytes of the reference script at this input.
 *   - If no script exists, explicitly set `0` for offline transaction building.
 *   - Example: `0` or `512`.
 *
 * @returns {MeshTxBuilder}
 *   Returns the current MeshTxBuilder instance for method chaining.
 *
 * @throws {Error}
 *   Throws if `txHash` is invalid or `txIndex` is negative.
 *
 * @example
 * // Minimal usage
 * txBuilder.txIn("9f3a2b...c8d4", 0);
 *
 * @see MeshTxBuilder
 * @see https://meshjs.dev/docs/txBuilder/txIn
 */

inline doc template for constants:

/**
 * @constant [CONSTANT_NAME]
 * @description
 * Short, clear one-liner of what this constant represents.
 * Mention Cardano/UTxO context or units if relevant (e.g., lovelace, bytes).
 *
 * @purpose
 * Why a developer would reference this value (defaults, limits, protocol constant, etc.).
 *
 * @example
 * // In context
 * const minFee = Math.max(calculatedFee, [CONSTANT_NAME]);
 *
 * @see https://meshjs.dev/docs/path/to/doc
 * @see mesh.relatedConstantOrFunction
 */

inline doc template for types:

/**
 * @typealias [TypeName]
 * @description
 * One-line definition of the shape and its role (domain model, DTO, on-chain concept, etc.).
 * Include Cardano specifics if relevant (Bech32, policy IDs, datum CBOR, etc.).
 *
 * @purpose
 * Why this type exists, where it’s used, and how it composes with other Mesh types.
 *
 * @property {<Type>} fieldName
 *   Description of the field:
 *   - Purpose
 *   - Constraints (e.g., valid Bech32 address, 64-char hex)
 *   - Example: `<example value>`
 *
 * @property {<Type>} anotherField
 *   Description...
 *
 * @remarks
 * **Invariants / edge cases**
 * - Describe any invariants (e.g., `quantity` must be a non-negative decimal string).
 * - Note optional vs required properties and serialization gotchas.
 *
 * @example
 * // Full example with realistic values
 * const y: [TypeName] = {
 *   fieldName: "<value>",
 *   anotherField: 123,
 * };
 *
 * @see mesh.RelatedType
 * @see https://meshjs.dev/docs/path/to/type
 */
export type [TypeName] = {
  fieldName: <Type>;
  anotherField?: <Type>;
};

• also reference existing website to see if any examples can be ported in
• feel free to use LLM in editor to make those inline docs, some quality assurance checks will be needed

[PiotrNap]

Great template! Where in the project do you see this residing?

[jinglescode]

Great template! Where in the project do you see this residing?

in the dev-facing packages, like transaction and wallet

we need lots of help getting inline docs real good for these LLM.

[PiotrNap]

I see it. I think putting everything inside source files will make them huge, and DX will suck. A better option would be to create separate markdown file and link it inside the current inline docs. Like so:

 /**
   * Native script - Set the reference input where it would also be spent in the transaction
   * @param txHash The transaction hash of the reference UTxO
   * @param txIndex The transaction index of the reference UTxO
   * @param spendingScriptHash The script hash of the spending script
   * @returns The MeshTxBuilder instance
   *  * Full examples & I/O traces: {@link docs/transaction}
   */
  simpleScriptTxInReference = (
    txHash: string,
    txIndex: number,
    spendingScriptHash?: string,
    scriptSize?: string,
  ) => {
    ...
  };

Wdyt @jinglescode ?

[jinglescode]

Yea. For sure full examples are needed to for how different components are linked and used together.
Feel free to provide a template for everyone to follow, need to get alignment from the rest too.

[PiotrNap]

Yes, totally! I propose the following template

(I took simpleScriptTxInReference as an example)

for inline docs:

  /**
   * Native script - Set the reference input where it would also be spent in the transaction
   * 
   * @param txHash The transaction hash of the reference UTxO
   * @param txIndex The transaction index of the reference UTxO
   * @param spendingScriptHash The script hash of the spending script
   * @returns The MeshTxBuilder instance
   * 
   * @throws Error when something ...
   * @throws Error when something else ...
   * 
   * @remarks
   * - Mutates internal builder state; input order is preserved.
   * - Reference inputs are consumed.
   * - Duplicate references are ignored (idempotent) // or “replaced/throws”—pick the truth.
   * - Full examples & I/O traces: see docs: https://docs.meshjs.dev/transactions/classes/MeshTxBuilder#simpleScriptTxInReference
   */

and for the full documentation (inside a separate markdown file):

# simpleScriptTxInReference (MeshTxBuilder)

## Purpose
Sets a reference input, which will be spend in the transaction.

## Precoditions
- `txHash`: Hex64 (64-char lowercase hex)
- `txIndex`: integer ≥ 0
- `spendingScriptHash`: 56-char hex (blake2b-224)

## Behavior
- Mutates builder; returns `this` (chainable).
- Reference UTxO is consumed.
- Input order preserved.
- Idempotency: adding the same reference twice is ignored/replaced/throws Error.

## Error Matrix
| Condition                            | Error message                     | When      |
|-------------------------------------|-----------------------------------|-----------|
| Queued TxIn item is of type Script  | `some message...`                 | call time |
| (...) NativeScript                  | `some message...`                 | call time |
| (...)                               | `...`                             | call time |

## Minimal Example
\`\`\`ts
tx.simpleScriptTxInReference(
  "9f3a2b7fa34c9e0d1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
  0,
  "4a1b...<56 hex total>...9c"
);
\`\`\`

## Full Example
\`\`\`ts
import { MeshTxBuilder } from "@meshsdk/core";

(...)
\`\`\`

## I/O Trace
…

That way we avoid cluttering source files, while ensuring that AI can understand the functionality by reading the markdown files.

[jinglescode]

@PiotrNap I have removed full examples from inline docs, and added constants and types.

[PiotrNap]

Hey, great job on adding constants and types! That’s definitely valuable.

Obviously, our goals with inline docs are: developer-friendly in IDEs, easy to maintain during changes, and AI-ingestible.

To make an informed decision and pick the best template, I suggest we run a quick experiment:

1. Take one file with different doc cases (constants, types, classes, methods)

2. Write it once with your template, and once with a thinner inline template (the one I proposed) + Markdown files

3. Ask a couple of devs to review both as if they were seeing the code for the first time

From their feedback, we’ll see which version has a better DX and AI clarity.

One thing worth keeping in mind are the upcoming planned arch changes, longer inline docs will likely create more churn. Keeping examples and edge cases in Markdown could reduce that overhead.

[smutyala1at]

I think it's better to use an AST parser to extract functions, classes, and interfaces etc, then use AI to generate inline docs and embed them directly, instead of having AI write inline docs inside code files, which makes developer experience worse.