Explain where args come from and their types (#2186)

* Explain where args come from and their types

* Update api.query.other.md

docs/cookbook/storage.md

@@ -38,10 +38,8 @@ In both these cases, entries/keys operate the same way, `.entries()` retrieving
 // Retrieves the entries for all slashes, in all eras (no arg)
 const allEntries = await api.query.staking.nominatorSlashInEra.entries();
 
-allEntries.forEach(([key, value]) => {
-  const era = key.args[0].toHuman();
-  const nominatorId = key.args[1].toString();
-
+// nominatorSlashInEra(EraIndex, AccountId) for the types of the key args
+allEntries.forEach(([{ args: [era, nominatorId] }, value]) => {
   console.log(`${era}: ${nominatorId} slashed ${value.toHuman()}`);
 });
 ```
@@ -52,6 +50,6 @@ While we can retrieve only the keys for a specific era, using a argument for the
 // Retrieves the keys for the slashed validators in era 652
 const slashedKeys = await api.query.staking.nominatorSlashInEra.keys(652);
 
-// key still contains (era, nominatorId) decoded, so args[1]
-console.log(`slashed: ${slashedKeys.map((k) => k.args[1].toString())`);
+// key args still contains [EraIndex, AccountId] decoded
+console.log(`slashed: ${slashedKeys.map(({ args: [era, nominatorId]}) => nominatorId.toString())`);
 ```

docs/start/api.query.multi.md

@@ -23,7 +23,7 @@ A couple of items to note in the example above: we don't call `account` directly
 ...
 
 // Retrieve a snapshot of the validators
-const validators = await api.query.session.validators();
+const validatorKeys = await api.query.session.validators.keys();
 
 // Subscribe to the balances for these accounts
 const unsub = await api.query.balances.account.multi(validators, (balances) => {

docs/start/api.query.other.md

@@ -71,18 +71,23 @@ exposures.forEach(([key, exposure]) => {
 });
 ```
 
-Here we are querying a double-map, so we supply 1 argument. No arguments on double-maps will be very costly, retrieving all the eras and associated entries. Additionally when `twox64_concat` & `blake2_concat` is used, the key `.args` will contain decoded values of the params, in this case it will contain the actual `AccountId` of the staker. (Since that was not supplied)
+To understand the usage of the `key.args`, you need to understand that map/doublemap keys are stored alongside their lookups. This means that the raw key has hashed parts as well as the raw data. The API will decode the keys and provide the raw key arguments in args. This would mean -
 
-In the same way as above we can simply do `.keys(activeEra.index): StorageKey[]` to retrieve all the keys here, including the individual keys args (available on maps with decodable hashing functions) -
+- if we are querying `api.query.staking.validators(validatorId: AccountId)` via `entries`, the `key.args` would be `[AccountId]`
+- if we are querying `api.query.staking.erasStakers(era: EraIndex, validatorId: AccountId)` via `entries`, the `key.args` would be `[EraIndex, AccountId]`
+
+the same applies to `.keys()` - here the list of keys also have the decoded args, as specified. You can think of `.args` as a tuple with the same types as the types required to retrieve a single entry in the map.
+
+In the first example we are querying a double-map, so we supply 1 argument. No arguments on double-maps will be very costly, retrieving all the eras and associated entries. In the same way as above we can simply do `.keys(activeEra.index): StorageKey[]` to retrieve all the keys here, including the individual keys args (available on maps with decodable hashing functions) -
 
 ```js
 // retrieve all the nominator keys
 const keys = await api.query.staking.nominators.keys();
 
-// extract the first key argument (AccountId) as string
-const nominatorIds = keys.map((key) => key.args[0].toString());
+// extract the first key argument [AccountId] as string
+const nominatorIds = keys.map(({ args: [nominatorId]) => nominatorId);
 
-console.log('all nominators:', nminatorIds.join(', '));
+console.log('all nominators:', nominatorIds.join(', '));
 ```
 
 ## State entries