Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[FR] - Better documentation for cardano-cli outputs

Open
  • Is something wrong?
#901 15 comments 1 reaction 1 assignee View on GitHub

Maintainers usually reply within 1 day

@CarlosLopezDeLara is already working on this.

Since Sep 18, 2024.

Assessment

This issue has not been assessed yet.

Description

documentation Stale

If you're deep in the code and involved in every new feature/change about cardano-cli, than this might not be an issue. But, for developers that are not that involved or that are new to cardano, its sometimes a bit of a pain to do a proper interpretation of certain cardano-cli query outputs.

I am not talking about the basic outputs like a utxo query or a stake-address-info query, those json outputs are well documented with there key naming schema alone imo.

When it comes to outputs like governance action queries, than its going to be more difficult. Let me give you an example:

 [
   null,
   [],
   {
   "keyHash-5f1b4429fe3bda963a7b70ab81135112a785afcf55ccd695b122e794": 379,
   "keyHash-9393c87a66b1f7dd4f9b486a49232de92e39e18b3b20ac4a539b4df2": 379
   },
   {
   "denominator": 7, 
   "numerator": 4
   }
]

If you are new to such an output you may wonder "whats the null entry?" or "whats the empty array" or "whats the number behind the keyHash entries"... etc. Btw, that object with denominator and numerator can also change to just a decimal number, if it has a finite number of decimals 😱 So, two different outputs for the same thing. Its not an issue, if documented!

Or for example:

[
   [
      [
         {
         "credential": {
         "keyHash": "c13582aec9a44fcc6d984be003c5058c660e1d2ff1370fd8b49ba73f"
         },
         "network": "Testnet"
         },
         1234567890
      ]
   ],
   null
]

Yes you can read out some basic infos, but there are 3 cascaded arrays. So, which one can actually hold more than one treasury withdrawal request? Can there even be more entries in an array or is it always just one?

As you can see, there are many of those.

This issue is not about changing the output! That is currently out of scope imo, because it would be too many breaking changes for 3rd party tools.

Its ok that the data output looks like it does, saving space and not having key/value pairs on every entry. But it lacks documentation. 😞

So, the intention of this gh issue is to raise awareness to somehow provide better documentation for existing and new developers and users in general.

It would be nice to have such a documentation on a website in a normal text form, or PDF, or similar.

Also it would be nice to have such a documentation like those familiar REST API documentation sites, where you can see all available commands and there outputs (maybe driven by goldentest sources?) via a TRY button or so. Developers are very familiar with such sites and they like them.

The documentation should of course cover every cardano-cli output, not just governance related ones like use in the examples.

Ok, this was just a quick first entry to raise this issue. Looking forwards to the discussions. 😃

Dominant language
Haskell
Stars
72
Forks
24
Avg merge
1d 5h
Merged PRs (30d)
9

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from IntersectMBO/cardano-cli

All issues in IntersectMBO/cardano-cli

Similar issues

More Haskell issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.