search

harmony-one / sdk

Javascript SDK of Harmony protocol.
MIT License
92 stars 43 forks source link

Create documentation for the SDK #16

Open john-harmony opened 4 years ago

john-harmony commented 4 years ago

Overview We'd like to create documentation for our developers. This will provide similar information as ethereum's web3 documentation

Task Overview

  1. Decide on documentation tooling (e.g. typedoc)
  2. Familiarize yourself with the tools by generating sample documentation.
  3. Decide on hosting mechanism (e.g. AWS or readthedocs or github)
  4. Document document creation process (e.g. documentation.md
  5. Generate the documentation and host it
  6. Refine the documentation so it is clearly structured and understandable
  7. Create a fitgap (comparison) of modules Harmony supports vs ethereum
  8. Create documentation standards for developers (e.g what comments need to be created for each module)
  9. Update the documentation so all modules are clearly documented (this may be done under a followup ticket

Acceptance Criteria a. Documentation is created and hosted b. Documentation has been shared and reviewed by internal team members c. Documentation has been shared and reviewed by external developers (p-dev or developers) d. Fitgap documentation is created (google shete) e. Documentation standards are created

john-harmony commented 4 years ago

Forked the repo for my local copy and did some initial work under the documentation branch https://github.com/john-harmony/sdk/blob/documentation/docs/README.md

Renewwen commented 4 years ago

I just created the draft documentation of our js-sdk, and deployed it on AWS s3, here is the link: https://harmony-js-sdk-doc.s3-us-west-1.amazonaws.com/index.html

john-harmony commented 4 years ago

Steps for generating documentation with reference Ethereum web3.js documentation process to generate readTheDocs

  1. Table of Contents is defined
  2. Create Overview 2.1 Getting Started 2.2 Promises 2.3 Glossary
  3. API Reference - with 10 packages underneath
  4. We'll refactor the documentation for packages to include methods and heirarchy later
Renewwen commented 4 years ago

Progress:

  1. Beautify the index page and put the general instruction into it.
  2. Simplify the navigation bar, list 8 API packages reference on the it.
  3. Add @annotation comments to every page, prepare for the next step.

The link is the same: https://harmony-js-sdk-doc.s3-us-west-1.amazonaws.com/index.html

if the content not change, clean the browser cache.

Renewwen commented 4 years ago

Start to revamp and create examples for our js-SDK.

Specifically, I am starting from the Blockchain class in the harmony-core package.

Here is the first example:

image

Renewwen commented 4 years ago

Position:

harmony-core/Blockchain

New Issues:

The param "returnObject" is not work in functions: getBlockbyHash and getBlockbyNumber

Has revamped:

hmy.blockchain.getBalance()
hmy.blockchain.getBlockNumber()
hmy.blockchain.getBlockByHash()
hmy.blockchain.getBlockByNumber()
hmy.blockchain.getBlockTransactionCountByHash()
hmy.blockchain.getBlockTransactionCountByNumber()
hmy.blockchain.getTransactionByBlockHashAndIndex()
hmy.blockchain.getTransactionByBlockNumberAndIndex()
hmy.blockchain.getTransactionByHash()
hmy.blockchain.getTransactionReceipt()
hmy.blockchain.getCxReceiptByHash()
hmy.blockchain.getCode()
hmy.blockchain.net_peerCount()
hmy.blockchain.net_version()
hmy.blockchain.getProtocolVersion()

Has hidden:

hmy.blockchain.constructor()
hmy.blockchain.setMessage()
hmy.blockchain.getRpcResult()
Renewwen commented 4 years ago

Hierarchy rebuild

  1. added contents to the index page for each sub-folder!
  2. hidden the necessary information of navigation bar

APIs revamped:

hmy.blockchain.getStorageAt()
hmy.blockchain.getTransactionCount()
hmy.blockchain.getShardingStructure()
hmy.blockchain.estimateGas()
hmy.blockchain.gasPrice()
hmy.blockchain.newPendingTransactions()
hmy.blockchain.syncing()
hmy.blockchain.logs()
hmy.blockchain.newBlockHeaders()
hmy.blockchain.sendTransaction()
hmy.blockchain.sendRawTransaction()
hmy.blockchain.createObservedTransaction()
hmy.blockchain.sendRawStakingTransaction()
hmy.blockchain.createObservedStakingTransaction()
Renewwen commented 4 years ago
  1. revamped the package: harmony-core
  2. optimized the other package, hidden some unnecessary information.
Renewwen commented 4 years ago

For the package: Account, revamped:

**Account**
account.getAddressFromShardID()
account.getShardBalance()
account.bech32Address
account.checksumAddress
account.bech32TestNetAddress
account.getShardsCount
account.getAddressFromShardID
account.getBalance()
account.getAddresses()
account.getShardBalance()
account.add()

**Wallet**
constructor()
wallet.addByPrivateKey()
wallet.accounts
wallet.addByMnemonic()
wallet.createAccount()
wallet.encryptAccount()
wallet.decryptAccount()
wallet.getAccount()
wallet.setMessenger()