Add API doc generation #12
Conversation
* Add a jsdoc configuration file. * Runs jsdoc on specific packages, capturing API details from source comments. * Converts the JSON from jsdoc into Asciidoc markup. * Adds reference documentation that includes the generated Asciidoc markup. * Adds NPM commands to package.json that allow the spell and includes CI checks to be executed explicitly. * make.sh now uses console colors to delineate processing stages.
SUMMARY.md
Outdated
| @@ -44,6 +44,7 @@ | |||
| * [Constants](reference/interbit/constants.md) | |||
| * [configSelectors](reference/interbit/configSelectors.md) | |||
| * [createChains()](reference/interbit/createChains.md) | |||
There was a problem hiding this comment.
Per your question in standup, it looks like we have an error in this API documentation. createChains is not actually a function, but is an object containing two functions: createChainsFromManifest and createChainsFromConfig(deprecated).
There was a problem hiding this comment.
When we shake the API tree, issues can sometimes fall out. 😄 I'll file an issue for this.
| @@ -57,7 +58,10 @@ | |||
| * [manifest file](reference/interbit-cli/manifest.adoc) | |||
| * [start](reference/interbit-cli/start.md) | |||
| * [interbit-covenant-tools](reference/interbit-covenant-tools/README.md) | |||
| * [validate()](reference/interbit-covenant-tools/validate.adoc) | |||
There was a problem hiding this comment.
These function names are not clear when they do not contain the additional scope of the exported object tree. Is there some way we could include the property path from module exports in the documentation for clarity?
There was a problem hiding this comment.
I may be reading the source incorrectly, but it looks to me like the top-level exports for interbit-covenant-tools includes validate(). So the documentation hierarchy matches exactly. Are you looking for some sort of breadcrumb, so that when you're viewing validate() you can see that it's a top-level function?
As an aside, the validate() function's source comments are lacking an @returns, and may need review for accuracy.
There was a problem hiding this comment.
You are correct, I had thought this was one of validateManifest or validateConfig but it is not. I forgot that export was in interbit-covenant-tools. Thanks!
| @@ -1,34 +1,41 @@ | |||
| #!/bin/bash | |||
|
|
|||
| echo 'Building documentation, please wait... ' | |||
| echo -e "\033[34mBuilding documentation, please wait...\033[0m" | |||
| @@ -23,6 +24,8 @@ | |||
| "start": "node index.js", | |||
| "build": "bash make.sh", | |||
| "test": "node node_modules/gitbook-plugin-interbit/scripts/doc_checks.js", | |||
| "spell": "node node_modules/gitbook-plugin-interbit/scripts/doc_checks.js -c spelling", | |||
|
Looks good! I just have a question about indicating the path for the export that maybe doesn't need to be addressed immediately but perhaps end up as a discussion & ticket instead. |
the remainder of the generated function API details.
topics have been separated into individual, function-specific topics.
can be called independently.
SUMMARY.md
Outdated
| * [connectToPeers()](reference/interbit/connectToPeers.adoc) | ||
| * [create()](reference/interbit/create.adoc) | ||
| * [createChains](reference/interbit/createChains.adoc) | ||
| * [createChainsFromConfig()](reference/interbit/createChainsFromConfig.adoc) |
There was a problem hiding this comment.
createChainsFromConfig() and createChainsFromManifest() are a subset of createChains
There was a problem hiding this comment.
Indeed, they are. What's the purpose behind that structure? It requires all callers to know about the structuring, but I can't tell why that hoop needs to be jumped through.
I'll update the TOC accordingly.
reference/interbit/README.adoc
Outdated
| Interbit offers the same features as the `interbit-cli` but in small | ||
| functions requireable for programmatically managing your chains. | ||
|
|
||
| The `interbit` package contains function to help you to: |
| @@ -0,0 +1,3 @@ | |||
| const { createChains: { createChainsFromManifest } } = require('interbit') | |||
|
|
|||
| const { ??? } = await createChainsFromManifest(cli, manifest) | |||
There was a problem hiding this comment.
The promise this function returns resolves to nothing. The context from createChainsFromConfig is generated dynamically during the function operation whereas when calling createChainsFromManifest it is already present in the manifest passed into params so unnecessary to return.
Uses infrastructure provided in the Interbit plugin to:
This strategy should allow use to enhance documentation with examples and other relevant content without cluttering the source code with such content.
Run
./make.shfrom the repo root to generate the documentation + API content.The doc CI compares generated Asciidoc markup for the API with included files; warnings are displayed if any files to be included do not exists and if any generated files are not included.
Run
npm run testto execute all of the doc CI checks.Run
npm run includesto just run the include checks.Run
npm run spellto just check the spelling within the docs source.