Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Added examples of transaction creation to Haddock #698

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Added examples of transaction creation to Haddock #698

wants to merge 2 commits into from

Conversation

palas
Copy link
Contributor

@palas palas commented Dec 3, 2024 •
edited
Loading

Changelog

- description: |
    Added example of transaction creation with traditional and experimental APIs to Haddock.
  type:
  - test
  - documentation

Context

Prompted by this slack discussion

How to trust this PR

Have a read of the haddock.

Checklist

  • Commit sequence broadly makes sense and commits have useful messages
  • New tests are added if needed and existing tests are updated. See Running tests for more details
  • Self-reviewed the diff

@palas palas self-assigned this Dec 3, 2024
smelc
smelc approved these changes Dec 5, 2024
View reviewed changes
cardano-api/test/cardano-api-test/Test/Cardano/Api/Experimental.hs Outdated Show resolved Hide resolved
cardano-api/src/Cardano/Api/Experimental.hs Outdated Show resolved Hide resolved
cardano-api/src/Cardano/Api/Experimental.hs Outdated Show resolved Hide resolved
cardano-api/src/Cardano/Api/Experimental.hs Outdated Show resolved Hide resolved
cardano-api/src/Cardano/Api/Experimental.hs Outdated Show resolved Hide resolved
Jimbo4350
Jimbo4350 reviewed Dec 9, 2024
View reviewed changes
Copy link
Contributor

@Jimbo4350 Jimbo4350 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice work 👍 . I would move the transaction creation haddocks to Cardano.Api.Experimental.Tx and point to it from here.

cardano-api/src/Cardano/Api/Experimental.hs Outdated Show resolved Hide resolved
cardano-api/src/Cardano/Api/Experimental.hs Outdated Show resolved Hide resolved
cardano-api/src/Cardano/Api/Experimental.hs Outdated
-- let sbe = Api.shelleyBasedEra :: Api.ShelleyBasedEra Api.ConwayEra
-- @
--
-- We can also derive it from 'ConwayEra' from 'Cardano.Api.Experimental' by using the 'convert' function:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So I think this is a bad UI. We should have a defaultTxBodyContent defined in an experimental module:

defaultTxBodyContent
  :: ()
  => Era era
  -> TxBodyContent BuildTx era

We want to avoid mixing the old api and the new api (but obviously allow for migration e.g via convert).

These haddocks are excellent but what we should do is have haddocks strictly describing the old api, the new api and how to migrate from the old to the new.

cardano-api/src/Cardano/Api/Experimental.hs Outdated Show resolved Hide resolved
cardano-api/src/Cardano/Api/Experimental.hs Outdated Show resolved Hide resolved
@palas palas force-pushed the haddock-for-experimental-api branch from ec017ee to bd4f6ba Compare December 11, 2024 11:33
@palas palas added documentation Improvements or additions to documentation test Adding or reworking tests labels Dec 11, 2024
@palas palas force-pushed the haddock-for-experimental-api branch from 0ddace3 to c9d390f Compare December 13, 2024 14:36
Jimbo4350
Jimbo4350 reviewed Dec 23, 2024
View reviewed changes
Copy link
Contributor

@Jimbo4350 Jimbo4350 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Getting there 👍

cardano-api/internal/Cardano/Api/Tx/Body.hs Outdated Show resolved Hide resolved
cardano-api/internal/Cardano/Api/Experimental/Tx.hs Outdated Show resolved Hide resolved
cardano-api/internal/Cardano/Api/Experimental/Tx.hs Outdated Show resolved Hide resolved
cardano-api/internal/Cardano/Api/Experimental/Tx.hs Outdated Show resolved Hide resolved
cardano-api/internal/Cardano/Api/Fees.hs Outdated Show resolved Hide resolved
cardano-api/internal/Cardano/Api/Fees.hs Outdated Show resolved Hide resolved
cardano-api/internal/Cardano/Api/Fees.hs Outdated Show resolved Hide resolved
cardano-api/internal/Cardano/Api/Fees.hs Outdated Show resolved Hide resolved
cardano-api/internal/Cardano/Api/Fees.hs Outdated Show resolved Hide resolved
@carbolymer
Copy link
Contributor

Outside of the scope of this PR: Maybe could use doctest to make sure that haddock examples didn't bitrot?

@palas
Copy link
Contributor Author

palas commented Jan 7, 2025 •
edited
Loading

Outside of the scope of this PR: Maybe could use doctest to make sure that haddock examples didn't bitrot?

Yes, I was thinking the same. Currently it is not checked by the CI, but at least it is easy to update if we do. And I made a couple of examples using this format in a different PR already (unrelated).

@palas palas force-pushed the haddock-for-experimental-api branch from f658862 to 25e9c36 Compare January 7, 2025 11:22
@palas palas mentioned this pull request Feb 6, 2025
Merged
3 tasks
@palas
Copy link
Contributor Author

palas commented Feb 11, 2025

Backup: https://github.com/IntersectMBO/cardano-api/tree/backup/haddock-for-experimental-api

@palas palas force-pushed the haddock-for-experimental-api branch 2 times, most recently from e6ee2ec to ab519b2 Compare February 11, 2025 17:50
@palas palas force-pushed the haddock-for-experimental-api branch from ab519b2 to cec9101 Compare February 11, 2025 17:56
Jimbo4350
Jimbo4350 reviewed Feb 12, 2025
View reviewed changes
cardano-api/src/Cardano/Api/Internal/Fees.hs Outdated Show resolved Hide resolved
cardano-api/src/Cardano/Api/Internal/Fees.hs Outdated Show resolved Hide resolved
cardano-api/src/Cardano/Api/Internal/Fees.hs Outdated Show resolved Hide resolved
cardano-api/src/Cardano/Api/Internal/Fees.hs Outdated Show resolved Hide resolved
cardano-api/src/Cardano/Api/Internal/Fees.hs Outdated Show resolved Hide resolved
cardano-api/src/Cardano/Api/Internal/Fees.hs Outdated Show resolved Hide resolved
Jimbo4350
Jimbo4350 requested changes Feb 12, 2025
View reviewed changes
Copy link
Contributor

@Jimbo4350 Jimbo4350 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Most of the links to modules are broken. We need to fix this. I also need you to work with @olgahryniuk to improve the flow of the documentation.

@palas palas force-pushed the haddock-for-experimental-api branch from 7d3ba15 to a083ac2 Compare February 13, 2025 10:38
@carbolymer
Copy link
Contributor

carbolymer commented Feb 13, 2025 •
edited
Loading

FYI https://github.com/IntersectMBO/cardano-api/actions/workflows/github-page.yml has a trigger, where you can specify a branch. It'll produce an artifact with haddocks e.g.: https://github.com/IntersectMBO/cardano-api/actions/runs/13306164579

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@Jimbo4350 Jimbo4350 Jimbo4350 requested changes

@smelc smelc smelc approved these changes

@dcoutts dcoutts Awaiting requested review from dcoutts dcoutts is a code owner

@erikd erikd Awaiting requested review from erikd erikd is a code owner

@newhoggy newhoggy Awaiting requested review from newhoggy newhoggy is a code owner

@kevinhammond kevinhammond Awaiting requested review from kevinhammond kevinhammond is a code owner

@CarlosLopezDeLara CarlosLopezDeLara Awaiting requested review from CarlosLopezDeLara CarlosLopezDeLara is a code owner

@disassembler disassembler Awaiting requested review from disassembler disassembler is a code owner

@carbolymer carbolymer Awaiting requested review from carbolymer carbolymer is a code owner

Requested changes must be addressed to merge this pull request.

Assignees

@palas palas

Labels
documentation Improvements or additions to documentation test Adding or reworking tests
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@palas @carbolymer @smelc @Jimbo4350