Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

[FR] - Better documentation for cardano-cli outputs

Aperta
  • Qualcosa non va?
#901 15 commenti 1 reazione 1 assegnatario Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@CarlosLopezDeLara ci sta già lavorando.

Dal 18/9/2024.

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

documentation

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. 😃

Lingua principale
Haskell
Stelle
72
Fork
25
Merge medio
2g 11h
PR unite (30g)
10

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di IntersectMBO/cardano-cli

Tutte le issue di IntersectMBO/cardano-cli

Issue simili

Altre issue su Haskell

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.