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

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions