search

gnolang / gno

Gno: An interpreted, stack-based Go virtual machine to build succinct and composable apps + gno.land: a blockchain for timeless code and fair open-source.
https://gno.land/
Other
900 stars 379 forks source link

[Docs]: Lack of information about `std.Test` functions #2817

Open MalekLahbib opened 2 months ago

MalekLahbib commented 2 months ago

Description

I tried to create a test file for a realm where I needed to send coins. I had to search the docs and the examples to figure out how to do it, and it's still not very clear for me:

The docs doesn't clarify this points and there's no link to an example where everything is explained. After a discussion yesterday with @moul, I opened this issue and wanted to know if I can work on example that can simplify and clarify the usage of this functions for a newcomer (I may need help to understand how this functions work exactly :) ). @leohhhn @michelleellen @zivkovicmilos @thehowl

thehowl commented 2 months ago

More examples are always welcome. You can do that as a starting explainer. Though, if you read some of the source and can make sense of it, I suggest you also try writing some "actual documentation".

After your example, if you want to tackle this issue properly, I suggest you two PRs:

  1. Make a PR adding godoc comments to the functions in gnovm/tests/stdlibs. This way, they can eventually show up in the gno doc output.
  2. Move these functions to the normal standard libraries (gnovm/stdlibs); but disable them entirely when not testing.

There is a PR that starts part of this work, but it'll be a while until I'm able to finish its vision: https://github.com/gnolang/gno/pull/2425

In the meantime, this is a good starting approach, as it allows us to have gno doc documentation for these functions, from the command line. If you want, you can also take up on the efforts to have this documentation on the web; see #522 and #526.