Incomplete API documentation

[dcolley]

Following this discussion: #4516 which has been closed.

The 'docs' site only deals with basic cases. Can we have complete API docs please?

I tried typedoc output

// typedoc.json
{
    "entryPoints": [
        "./packages/api/src/index.ts",
        "./packages/api-base/src/index.ts",
        "./packages/api-derive/src/index.ts",
        "./packages/rpc-core/src/index.ts",
        "./packages/typegen/src/index.ts",
        "./packages/types-augment/src/index.ts",
        "./packages/types-create/src/index.ts",
        "./packages/types-support/src/index.ts",
        "./packages/api-augment/src/index.ts",
        "./packages/api-contract/src/index.ts",
        "./packages/rpc-augment/src/index.ts",
        "./packages/rpc-provider/src/index.ts",
        "./packages/types/src/index.ts",
        "./packages/types-codec/src/index.ts",
        "./packages/types-known/src/index.ts"
    ],
    "out": "typedocs"
}

Then use it like:

git clone https://github.com/polkadot-js/api
cd api
yarn install
# npm|yarn install -g serve
# npm|yarn install --save-dev typedoc
./node_modules/.bin/typedoc --options ./typedoc.json --tsconfig ./tsconfig.json
serve typedocs

Open http://localhost:3000

The result is only showing a portion of the docs and the sections don't [seem to] know about each other.

For example, api.query returns QueryableStorage<ApiType>, yet there is no link to that definition.

Something like https://swagger.io would be great!

Is there a better option? I'm happy to work on this if people find it useful.

[jacogr]

Used to have these right at the start, but typedoc output has not been worked on or looked at in ages. It is very unlikely to be resurrected by me, since there is only so many hours in a day and so many days in a week. (Have really not had a weekend "beer & docs" effort for quite a long time)

However, PRs would certainly be very welcome if they get these into shape. (It is obviously much easier maintaining them once they have reached some level of usefulness, as opposed to getting it to that point.)

Some comments -

• in the above above, the _* should definitely be suppressed
• the QueryableStorage<..> is actually tricky to link - since it is augmented on a per-chain level, i.e. Substrate doesn't have defaults to what needs to be in storage, it it completely up to the chain and decorated from metadata

TL;DR Yes, there are actually critical and really nice to have in place, so effort would be well spent. (There is just no gap for me to attack it, it doesn't mean it is not very welcome)

[dcolley]

Oh dear... "beer & docs"!
That's actually something I would sign up for ;)

I also have to comment out loads of sections to avoid errors like this:

Error: packages/api-augment/src/kusama/events.ts:707:5 - error TS2717: Subsequent property declarations must have 
the same type.  Property 'proxy' must be of type '{ [key: string]: AugmentedEvent<ApiType, AnyTuple>; Announced: 
AugmentedEvent<ApiType, [AccountId32, AccountId32, H256]>; AnonymousCreated: AugmentedEvent<...>; ProxyAdded: 
AugmentedEvent<...>; ProxyExecuted: AugmentedEvent<...>; ProxyRemoved: AugmentedEvent<...>; }', but here has 
type '{ [key: string]: AugmentedEvent<ApiType, AnyTuple>; Announced: AugmentedEvent<ApiType, [AccountId32, 
AccountId32, H256]>; AnonymousCreated: AugmentedEvent<...>; ProxyAdded: AugmentedEvent<...>; ProxyExecuted: 
AugmentedEvent<...>; ProxyRemoved: AugmentedEvent<...>; }'.

707     proxy: {
        ~~~~~

  packages/api-augment/src/substrate/events.ts:688:5
    688     proxy: {
            ~~~~~
    'proxy' was also declared here.

These declarations are similar between kusama, polkadot and substrate but not exact - and typedoc baulks.

I'll keep plugging away at it - I need it anyway for my own purposes.
Is there any treasury bounty for this sort collaboration?

[jacogr]

The duplication is intentional - you would only include one of those files in your project at a time, eg. https://polkadot.js.org/docs/api/FAQ#since-upgrading-to-the-7x-series-typescript-augmentation-is-missing

If one needs to be made part of a project, I guess the Substrate version is the one. (None of the augmented files are include by default, since chains will generate their own augmentation, as per the link above)

In the process of setting up a tip bot (like we have for Substrate contributions), but can also submit that manually.