Skip to content

docs: Data guide is missing withSchema, toHash, DataEncoded, DataError, and a helper API reference #154

@solidsnakedev

Description

@solidsnakedev

Problem

The Data guide page at `docs/content/docs/encoding/data.mdx` covers the five PlutusData types and basic CBOR encoding well, but is missing several important areas of the `Data` module.

Missing Sections

Data.withSchema() — The most important bridge between raw `Data` and `TSchema`. The page mentions TSchema at the bottom but never explains `Data.withSchema()` itself, the codec it returns (`toData`, `fromData`, `toCBORHex`, `toCBORBytes`, `fromCBORHex`, `fromCBORBytes`), or where this API lives relative to raw Data manipulation.

Data.toHash() — Computing a datum hash from PlutusData is a core operation when attaching non-inline datums to transactions. This is absent from the guide.

DataEncoded type — The JSON-serializable representation of PlutusData (used by node APIs, block explorers, and CML interop). Not mentioned.

DataError — Error handling when decoding fails. The error type exists but is never referenced in the guide.

Helper API reference — `Data.constr()`, `Data.map()`, `Data.toCBORHex()`, `Data.fromCBORHex()`, `Data.toCBORBytes()`, `Data.fromCBORBytes()`, `Data.equals()` are all used in examples but there is no dedicated reference section listing each with its signature and behavior.

Constr class vs constr helper — The `Constr` class (with `index` and `fields`) and the `Data.constr()` convenience function both exist but the distinction is not explained anywhere in the guide.

Acceptance Criteria

  • `Data.withSchema()` has its own section with codec API documented (`toData`, `fromData`, `toCBORHex`, etc.)
  • `Data.toHash()` is documented with an example showing datum hash computation
  • `DataEncoded` type is explained — what it is, where it comes from, when you encounter it
  • `DataError` and decoding error handling is covered
  • A Reference section enumerates all helper exports with signatures and one-line descriptions
  • `Constr` class vs `Data.constr()` helper distinction is clarified
  • All examples use `twoslash` code fences and compile

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions