🤯 [Guide] Discover and learn cool features by contributing to the Documentation!

Hello everybody!

As you know, contributions to all the AE tooling is always welcome, especially more examples is what is being often asked for. I’d like to shine some light on how to make it most fun for you while you also discover interesting features and actually learn a lot ! Seriously, so many times I discovered cool features for libraries I used by just casually digging around its documentation curiously.
There will even be bounties on some to-dos, but there will be a separate thread I will link here later.

And here is how it’s done ! :slight_smile:

0. Fork the JS SDK on Github:


(Disclaimer: Excuse the bugged documentation navigation for now, it is caused by a bug upsteam, we’re working on a solution for that. If you prefer the less good-looking default template with working nav, take the developbranch https://github.com/aeternity/aepp-sdk-js)

0.1 git clone the repo to your computer and run $ npm install.

1. generate and serve the docs with $ mkdocs serve and follow the link in the output to open the doc on your computer.

2. Find some documentation missing meaningful code examples. For demo purposes, let’s go here:image
(The nav may change in the future, but that doesn’t matter for us now.

So, what do we have here ?
This module is missing meaningful code examples :scream:


Let’s learn how to use SDK functions by creating a code example ! :rocket:

3. Think of a cool example
Let’s write one for the constructor and add how to import it in NodeJS !

First, for messing around and testing our code, we create a folder outside the JS SDK to initiate a new NPM project inside it with $ npm init , then install the JS SDK in it with $ npm i @aeternity/aepp-sdk

Just create an index.js and paste the code from the quickstart guide. Take a close look: It requires you to provide a public and private key. Replace the placeholders with the values generated from this short script:

const { Crypto } = require('@aeternity/aepp-sdk')
const keypair = Crypto.generateKeyPair()
console.log(`Secret key: ${keypair.secretKey}`)
console.log(`Public key: ${keypair.publicKey}`)

and if you look closely, you can already build a code example from your Quickstart code for MemoryAccount() like the following one, because you have all the information available already:

//JS
import MemoryAccount from '@aeternity/aepp-sdk/es/account/memory'

//NodeJS
const { Universal: MemoryAccount } = require('@aeternity/aepp-sdk')

const account = MemoryAccount({ keypair: { secretKey: 'c3e717...**censored**...33d1d0', publicKey: 'ak_rh5G5EeDNCYyyKUyY9DSrMDjbw325HSvQdLXGgcTmDjaQf1Af', } })

Cool story bro, but where do I put this now ?!

The Docs are being automatically generated from annotations in the SDK’s source files. The title in the SDK doc already tells us where to watch: Hop back to the JS-SDK folder and go to /es/account/memory.js . What you are looking for is the @example parts of the JSdoc:


Here, in the general module description, we provided info on correct importing. On the function further below, we add the code:

And then we proudly take a look at our work: Run $ mkdocs serve again and navigate to the page.

Things don’t have to be totally feature-complete always. Feel free to add as much information or advice as you know.

...

In this example, I’ll probably add the advice that the Account is a stamp and only to be used together with SDK functions that explicitly ask for it, on its own it’s useless.

Commit your changes, push, go to GitHub, open a pullrequest to the develop (!) branch of the Aeternity SDK repository (ask if you need help) and be celebrated as a contributor! :tada::tada:

Now give it a shot and start with something easy but very cool. Did you know about all the nice tricks the SDK allows you to do with Aeternity? Look at all the crypto utility functions library, or all the things you can make the Aeternity blockchain tell you with the chain utility functions. Or look at the three different functions for transfering funds, which all serve a different purpose ! :mortar_board:

Let me see what you guys can come up with ! :drum:

3 Likes

If you have an issue with a function you want to write about, post it on our soon-to-be StackExchange to supoprt it becoming a thing soon and then share your issue in the forum ! We are there to help, all problems are welcome and are good knowledge to appear on google !

4 Likes