Please add examples to the code comments on ic_cdk functions in all the modules

Please add some examples inline in the ic_cdk code comments so that they appear here in the different functions available in the different modules.

For example:

This is the ic_cdk API for an inter canister call. It doesn’t have any examples listed in the docs, only a terse one liner explaining that this uses the System API and expected error.

However, there’s no examples available on how to call it, what to pass as arguments and what to expect as a response.

This would not be a problem if the API was really straightforward and idiot-proof. But that’s not the case.

After struggling to make it work, a forum search brings up this forum post

It goes over how custom struct arguments need to derive specific traits and how arguments are expected to be tuples, even single entries, which is counter-intuitive and trips a lot of people. The devs asking questions in the above thread are some of the most prolific Rust devs on this forum @senior.joinu @lastmjs

This information needs to be put in the documentation examples in the code comments so that they surface in the official documentation and editor intellisense tooling automatically.

Here’s an example of documentation comments done right.

6 Likes

Tagging @lwshang @kpeacock @ericswanson since they are listed as the owners of the package

image

I noted it for our tasks, but I can’t make any promises when we’ll get to it.

(internal ticket link in case I’m asked for status updates)

Of course. I understand.

Thank you for the update :slight_smile:

Just in case you feel like fixing it NOW: we’re always happy to accept PRs that improve the situation :smile:

1 Like

I definitely don’t know how all the APIs work. But I will try and add to the ones I’m aware of :slight_smile:
I’ll send the ic_cdk repo a PR with a couple to get some feedback

We are currently crunching hard to ship a release, but once I have some downtime, will help do this :slight_smile:

2 Likes