Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Automated generation and publishing of contract API docs with solidity-docgen #880

Merged
merged 29 commits into from
Jun 7, 2022

Conversation

d10r
Copy link
Collaborator

@d10r d10r commented Jun 2, 2022

First PR for #383

Changes:

  • added a hardhat plugin for automated doc generation with solidity-docgen - since v0.6 (rewrite) of that package, the hardhat plugin is the main (only?) way to operate it
  • added handlebar templates to get better (hopefully) results (layout, formatting...)
  • adapted natspec docs in interface files to yield better results, e.g. by using @custom tags recently introduced

There's still some work to be done, will be documented in the ticket

@d10r d10r changed the title Solidity docgen Automated generation and publishing of contract API docs with solidity-docgen Jun 3, 2022
@d10r d10r marked this pull request as ready for review June 3, 2022 10:20
@d10r d10r requested review from hellwolf and a team as code owners June 3, 2022 10:20
@saflamini
Copy link
Contributor

@d10r

On the titles for each function and event, what if we format:

  • Functions with a () appended to the end? "createFlow()" instead of "fn createFlow" ?
  • Events with 'Event' appended to the end of the description? "flowUpdated Event" instead of "Event flowUpdated"

One other macro point: there's a lot of room for improvement in our interface comments. Many of the functions lack descriptions of the function and their associated return values/parameters.
Improving the quality of our comments in each interface file is an effort that I can help lead.

run: |
yarn workspace @superfluid-finance/ethereum-contracts docgen

# Code to upload to refs.superfluid.finance. The md files aren't useful there, need to render first
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do you want to keep these as comments or clean it up?

@@ -11582,7 +11582,7 @@ gzip-size@^6.0.0:
dependencies:
duplexer "^0.1.2"

handlebars@^4.0.1, handlebars@^4.7.6:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

these seems suspicious, could use npm ls handlebars to checkout how these dependencies came about.

not a big deal, but worth cleanup if easy.

Copy link
Contributor

@hellwolf hellwolf left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looking good

@hellwolf
Copy link
Contributor

hellwolf commented Jun 6, 2022

@d10r shoudl we merge?

@hellwolf hellwolf linked an issue Jun 7, 2022 that may be closed by this pull request
@hellwolf hellwolf merged commit ace5c31 into dev Jun 7, 2022
@hellwolf hellwolf deleted the solidity-docgen branch June 7, 2022 09:11
@github-actions
Copy link

github-actions bot commented Jun 7, 2022

XKCD Comic Relif

Link: https://xkcd.com/880
https://xkcd.com/880

0xdavinchee added a commit that referenced this pull request Jun 11, 2022
* bump sdk-core versions + CHANGELOG update (#868)

* Use `abi.encodeCall` (#869)

* use abi.encodeCall

* abi.encodeWithSelector replaced by abi.encodeCall

* SimpleACLResolver encodeCall

* Employment loan fix (#877)

* add callback checks and remove state var redundancy

* clean up mockv3aggregator file

* make CFA_ID constant and fix ctx return redundancy in callback

Co-authored-by: Sam Flamini <sam_flamini@Sams-MacBook-Air.local>

* Workflow Edits + Subgraph 1.4.1 Patch (#872)

* Fix budget nft (#878)

* budget nft variables cleanup, remove migrations.sol

* remove unecessary cfa assertion in constructor

* more detailed readme

* add deploy + interaction scripts

* change wording in readme

Co-authored-by: Sam Flamini <sam_flamini@Sams-MacBook-Air.local>

* Stream to distribution example (#871)

* init new example

* updated stream-in-distribute-out base

* update tests/mocks

* fix

* bug fixes, added tests

* added test script, minor bug fixes

* added test for IDA approval

* added comments on validation

Co-authored-by: davinchee <0xdavinchee@gmail.com>

* Map flow update type to FlowUpdatedEvent (#882)

Co-authored-by: 0xdavinchee <0xdavinchee@gmail.com>

* Remove ethers support from js-sdk (#876)

* Remove ethers support

* Fix eslint errors

* Reset yarn.lock

* Remove readme examples with ethers

Co-authored-by: Miao ZhiCheng <miao@superfluid.finance>
Co-authored-by: 0xdavinchee <0xdavinchee@gmail.com>

* Branch Policy Sync (#881)

* Branch Policy Sync

## CI Canary

* Add test current subgraph implementation on previous SDK-Core versions

## CI Pre Release - SDK-Core

* Remove local subgraph w/ SDK-Core test
* Keep Subgraph indexing completeness
* Keep SDK-Core release test against v1 matic endpoint
* Test SDK-Core release against dev goerli endpoint (for double checking)

## CI Pre Release - Subgraph

* replace local subgraph test with dev endpoint test
* add subgraph integration test for double checking
* keep previous SDK-version tests against dev endpoint and local subgraph

* remove local test

* remove local-subgraph-url leak

* local-subgraph-url removed from yml files, this is handled in the test file now (based on SUBGRAPH_RELEASE_TAG)
* workflows changed accordingly

* unused import ts fix

Co-authored-by: Miao ZhiCheng <miao@superfluid.finance>

* hot-fuzz remove temporary instructions fix (#886)

* Automated generation and publishing of contract API docs with solidity-docgen (#880)

* calculateMaybeCriticalAtTimestamp is calculating for "insolvency time" instead of "critical time" (#885)

* removed deposit from critical timestamp calculation

* edited variable name as per request

* as per review comments

* handled 1st  case returing old maybe_critical_timestamp

* use toBN()

* as per comment

* maybeCriticalAt should be initialized at null

* updated test method

* updated sdk core entity

* added comment and throwing error

* added comment and throwing error

Co-authored-by: davinchee <0xdavinchee@gmail.com>

* Fix rewards dist token (#879)

* remove unnecessary host var

* change import schema

* ensure consistent styling in imports

* add env to gitignore for safety

* rm extra fluff from readme

Co-authored-by: Sam Flamini <sam_flamini@Sams-MacBook-Air.local>

Co-authored-by: saflamini <43142465+saflamini@users.noreply.github.com>
Co-authored-by: Sam Flamini <sam_flamini@Sams-MacBook-Air.local>
Co-authored-by: Joshua Trujillo <Jtriley15@gmail.com>
Co-authored-by: Kaspar Kallas <kaspar@superfluid.finance>
Co-authored-by: elvijsTDL <77115130+elvijsTDL@users.noreply.github.com>
Co-authored-by: Miao ZhiCheng <miao@superfluid.finance>
Co-authored-by: Axe <ngmachado@users.noreply.github.com>
Co-authored-by: Didi <git@d10r.net>
Co-authored-by: Mehul Soni <65469737+msoni89@users.noreply.github.com>
0xdavinchee added a commit that referenced this pull request Jun 30, 2022
* bump sdk-core versions + CHANGELOG update (#868)

* Use `abi.encodeCall` (#869)

* use abi.encodeCall

* abi.encodeWithSelector replaced by abi.encodeCall

* SimpleACLResolver encodeCall

* Employment loan fix (#877)

* add callback checks and remove state var redundancy

* clean up mockv3aggregator file

* make CFA_ID constant and fix ctx return redundancy in callback

Co-authored-by: Sam Flamini <sam_flamini@Sams-MacBook-Air.local>

* Workflow Edits + Subgraph 1.4.1 Patch (#872)

* Fix budget nft (#878)

* budget nft variables cleanup, remove migrations.sol

* remove unecessary cfa assertion in constructor

* more detailed readme

* add deploy + interaction scripts

* change wording in readme

Co-authored-by: Sam Flamini <sam_flamini@Sams-MacBook-Air.local>

* Stream to distribution example (#871)

* init new example

* updated stream-in-distribute-out base

* update tests/mocks

* fix

* bug fixes, added tests

* added test script, minor bug fixes

* added test for IDA approval

* added comments on validation

Co-authored-by: davinchee <0xdavinchee@gmail.com>

* Map flow update type to FlowUpdatedEvent (#882)

Co-authored-by: 0xdavinchee <0xdavinchee@gmail.com>

* Remove ethers support from js-sdk (#876)

* Remove ethers support

* Fix eslint errors

* Reset yarn.lock

* Remove readme examples with ethers

Co-authored-by: Miao ZhiCheng <miao@superfluid.finance>
Co-authored-by: 0xdavinchee <0xdavinchee@gmail.com>

* Branch Policy Sync (#881)

* Branch Policy Sync

## CI Canary

* Add test current subgraph implementation on previous SDK-Core versions

## CI Pre Release - SDK-Core

* Remove local subgraph w/ SDK-Core test
* Keep Subgraph indexing completeness
* Keep SDK-Core release test against v1 matic endpoint
* Test SDK-Core release against dev goerli endpoint (for double checking)

## CI Pre Release - Subgraph

* replace local subgraph test with dev endpoint test
* add subgraph integration test for double checking
* keep previous SDK-version tests against dev endpoint and local subgraph

* remove local test

* remove local-subgraph-url leak

* local-subgraph-url removed from yml files, this is handled in the test file now (based on SUBGRAPH_RELEASE_TAG)
* workflows changed accordingly

* unused import ts fix

Co-authored-by: Miao ZhiCheng <miao@superfluid.finance>

* hot-fuzz remove temporary instructions fix (#886)

* Automated generation and publishing of contract API docs with solidity-docgen (#880)

* calculateMaybeCriticalAtTimestamp is calculating for "insolvency time" instead of "critical time" (#885)

* removed deposit from critical timestamp calculation

* edited variable name as per request

* as per review comments

* handled 1st  case returing old maybe_critical_timestamp

* use toBN()

* as per comment

* maybeCriticalAt should be initialized at null

* updated test method

* updated sdk core entity

* added comment and throwing error

* added comment and throwing error

Co-authored-by: davinchee <0xdavinchee@gmail.com>

* Fix rewards dist token (#879)

* remove unnecessary host var

* change import schema

* ensure consistent styling in imports

* add env to gitignore for safety

* rm extra fluff from readme

Co-authored-by: Sam Flamini <sam_flamini@Sams-MacBook-Air.local>

* fix isValidAppAction

* Increase Code Coverage (#891)

    Superfluid.sol fully covered
    FullUpgradableSuperTokenProxy.sol fully covered
    TestToken fully covered
    UUPSProxiable.sol fully covered

* Fix nft billboard (#883)

* Test Previous SDK-Core Based off dev (#893)

* Simple IDA Example (#890)

* initial commit

* deploy scripts and docs

* clean up

* comment out goerli network option

Co-authored-by: Joel Jesudason <62968241+JoelJesudason@users.noreply.github.com>
Co-authored-by: Miao ZhiCheng <miao@superfluid.finance>
Co-authored-by: saflamini <43142465+saflamini@users.noreply.github.com>
Co-authored-by: Sam Flamini <sam_flamini@Sams-MacBook-Air.local>

* Solidity 0.8.14 (#896)

* bump ethereum-contracts version to 1.3.0

* Production deployment script fixes (#821)

Co-authored-by: Bertrand Juglas <b@juglas.name>
Co-authored-by: Didi <git@d10r.net>
Co-authored-by: xdavinchee <0xdavinchee@gmail.com>

* updated CHANGELOG

* Queue up FAILED_VERIFICATIONS (#900)


Co-authored-by: didi <git@d10r.net>

* Make SDK-core test cases independant from each other (#901)

* Make sdk-core tests strong and independant

* Remove commented out code

* formatting

Co-authored-by: davinchee <0xdavinchee@gmail.com>
Co-authored-by: Miao ZhiCheng <miao@superfluid.finance>

* [SDK-REDUX] Pass in `signer` and `overrides` through mutation payload (#904)

* Pass in signer and ether's overrides through mutation args

* remove them from cache key

* Fix example project with new signer usage

* Update readme & changelog

* Simple CFA Example (#888)

* GH workflow for deploying to mainnets (#905)

* Protocol monorepo status slack bot (#906)

* Subgraph Fixes + Refactor (#909)

* Remove `networkId` and `dataMode` from Framework Initialization (#910)

* Update handler.publish-pr-packages.yml (#922)

* Token spreader fixes (#913)

* revised deploy script to use sf framework

* demo scripts

* typo, env template tweak, readme into tutorial

* made build script executable

* fix hardhat config (type hint), rename PASS_PHRASE to MNEMONIC, IDE auto-removal of trailing spaces

* lock file

Updated README with tutorial, made improved scripts for tutorial demonstration, included lock file (which was forced as it is gitignored at base of repository) for npm installation, didi smol tweaks

Co-authored-by: Joel Jesudason <62968241+JoelJesudason@users.noreply.github.com>
Co-authored-by: didi <git@d10r.net>

* BNB Chain Support (#925)

ethereum-contracts, js-sdk, sdk-core, subgraph

Co-authored-by: didi <git@d10r.net>

* [SDK-REDUX] Mark on a tracked transaction whether Subgraph polling was successful (#921)

* SDK-Core Subgraph Changes (#917)

* mapping updates
* add missing token property to super token events
* add governanceAddress to superfluid governance event entities
* add TokenStatisticLog entity
* add totalAmountStreamedIn, totalAmountStreamedOut properties to ATS and ATSLog entities
* tests for new properties on ATS
* tests for new TSLog entity
* undo manual accounting for balance
* always use rpc to get balance and update
* add gasPrice to event entities
* code cleanup + add some standards for subgraph indexing functions:
  * prepend `_` to create event/log entity functions: `_createEventNameEventEntity`
  * handler functions should follow format of handleEventName
* minor mapping file structure cleanup - separate to different sections
* sdk core subgraph changes
* add gasPrice test
* add support of log queries to sdk-redux
* token and governanceAddress properly mapped
* governanceAddress and token added

Co-authored-by: Kaspar Kallas <kaspar@superfluid.finance>

* Subgraph Release Branch Conflicts Fix (#934)

* SDK-Core Release Branch Conflicts Fix (#932)

* bump version (#937)

Co-authored-by: saflamini <43142465+saflamini@users.noreply.github.com>
Co-authored-by: Sam Flamini <sam_flamini@Sams-MacBook-Air.local>
Co-authored-by: Joshua Trujillo <Jtriley15@gmail.com>
Co-authored-by: Kaspar Kallas <kaspar@superfluid.finance>
Co-authored-by: elvijsTDL <77115130+elvijsTDL@users.noreply.github.com>
Co-authored-by: Miao ZhiCheng <miao@superfluid.finance>
Co-authored-by: Axe <ngmachado@users.noreply.github.com>
Co-authored-by: Didi <git@d10r.net>
Co-authored-by: Mehul Soni <65469737+msoni89@users.noreply.github.com>
Co-authored-by: Sunny Jaycer <62968241+sunnyjaycer@users.noreply.github.com>
Co-authored-by: Joel Jesudason <62968241+JoelJesudason@users.noreply.github.com>
Co-authored-by: Bertrand Juglas <b@juglas.name>
0xdavinchee added a commit that referenced this pull request Jul 4, 2022
* bump sdk-core versions + CHANGELOG update (#868)

* Use `abi.encodeCall` (#869)

* use abi.encodeCall

* abi.encodeWithSelector replaced by abi.encodeCall

* SimpleACLResolver encodeCall

* Employment loan fix (#877)

* add callback checks and remove state var redundancy

* clean up mockv3aggregator file

* make CFA_ID constant and fix ctx return redundancy in callback

Co-authored-by: Sam Flamini <sam_flamini@Sams-MacBook-Air.local>

* Workflow Edits + Subgraph 1.4.1 Patch (#872)

* Fix budget nft (#878)

* budget nft variables cleanup, remove migrations.sol

* remove unecessary cfa assertion in constructor

* more detailed readme

* add deploy + interaction scripts

* change wording in readme

Co-authored-by: Sam Flamini <sam_flamini@Sams-MacBook-Air.local>

* Stream to distribution example (#871)

* init new example

* updated stream-in-distribute-out base

* update tests/mocks

* fix

* bug fixes, added tests

* added test script, minor bug fixes

* added test for IDA approval

* added comments on validation

Co-authored-by: davinchee <0xdavinchee@gmail.com>

* Map flow update type to FlowUpdatedEvent (#882)

Co-authored-by: 0xdavinchee <0xdavinchee@gmail.com>

* Remove ethers support from js-sdk (#876)

* Remove ethers support

* Fix eslint errors

* Reset yarn.lock

* Remove readme examples with ethers

Co-authored-by: Miao ZhiCheng <miao@superfluid.finance>
Co-authored-by: 0xdavinchee <0xdavinchee@gmail.com>

* Branch Policy Sync (#881)

* Branch Policy Sync

## CI Canary

* Add test current subgraph implementation on previous SDK-Core versions

## CI Pre Release - SDK-Core

* Remove local subgraph w/ SDK-Core test
* Keep Subgraph indexing completeness
* Keep SDK-Core release test against v1 matic endpoint
* Test SDK-Core release against dev goerli endpoint (for double checking)

## CI Pre Release - Subgraph

* replace local subgraph test with dev endpoint test
* add subgraph integration test for double checking
* keep previous SDK-version tests against dev endpoint and local subgraph

* remove local test

* remove local-subgraph-url leak

* local-subgraph-url removed from yml files, this is handled in the test file now (based on SUBGRAPH_RELEASE_TAG)
* workflows changed accordingly

* unused import ts fix

Co-authored-by: Miao ZhiCheng <miao@superfluid.finance>

* hot-fuzz remove temporary instructions fix (#886)

* Automated generation and publishing of contract API docs with solidity-docgen (#880)

* calculateMaybeCriticalAtTimestamp is calculating for "insolvency time" instead of "critical time" (#885)

* removed deposit from critical timestamp calculation

* edited variable name as per request

* as per review comments

* handled 1st  case returing old maybe_critical_timestamp

* use toBN()

* as per comment

* maybeCriticalAt should be initialized at null

* updated test method

* updated sdk core entity

* added comment and throwing error

* added comment and throwing error

Co-authored-by: davinchee <0xdavinchee@gmail.com>

* Fix rewards dist token (#879)

* remove unnecessary host var

* change import schema

* ensure consistent styling in imports

* add env to gitignore for safety

* rm extra fluff from readme

Co-authored-by: Sam Flamini <sam_flamini@Sams-MacBook-Air.local>

* fix isValidAppAction

* Increase Code Coverage (#891)

    Superfluid.sol fully covered
    FullUpgradableSuperTokenProxy.sol fully covered
    TestToken fully covered
    UUPSProxiable.sol fully covered

* Fix nft billboard (#883)

* Test Previous SDK-Core Based off dev (#893)

* Simple IDA Example (#890)

* initial commit

* deploy scripts and docs

* clean up

* comment out goerli network option

Co-authored-by: Joel Jesudason <62968241+JoelJesudason@users.noreply.github.com>
Co-authored-by: Miao ZhiCheng <miao@superfluid.finance>
Co-authored-by: saflamini <43142465+saflamini@users.noreply.github.com>
Co-authored-by: Sam Flamini <sam_flamini@Sams-MacBook-Air.local>

* Solidity 0.8.14 (#896)

* bump ethereum-contracts version to 1.3.0

* Production deployment script fixes (#821)

Co-authored-by: Bertrand Juglas <b@juglas.name>
Co-authored-by: Didi <git@d10r.net>
Co-authored-by: xdavinchee <0xdavinchee@gmail.com>

* updated CHANGELOG

* Queue up FAILED_VERIFICATIONS (#900)


Co-authored-by: didi <git@d10r.net>

* Make SDK-core test cases independant from each other (#901)

* Make sdk-core tests strong and independant

* Remove commented out code

* formatting

Co-authored-by: davinchee <0xdavinchee@gmail.com>
Co-authored-by: Miao ZhiCheng <miao@superfluid.finance>

* [SDK-REDUX] Pass in `signer` and `overrides` through mutation payload (#904)

* Pass in signer and ether's overrides through mutation args

* remove them from cache key

* Fix example project with new signer usage

* Update readme & changelog

* Simple CFA Example (#888)

* GH workflow for deploying to mainnets (#905)

* Protocol monorepo status slack bot (#906)

* Subgraph Fixes + Refactor (#909)

* Remove `networkId` and `dataMode` from Framework Initialization (#910)

* Update handler.publish-pr-packages.yml (#922)

* Token spreader fixes (#913)

* revised deploy script to use sf framework

* demo scripts

* typo, env template tweak, readme into tutorial

* made build script executable

* fix hardhat config (type hint), rename PASS_PHRASE to MNEMONIC, IDE auto-removal of trailing spaces

* lock file

Updated README with tutorial, made improved scripts for tutorial demonstration, included lock file (which was forced as it is gitignored at base of repository) for npm installation, didi smol tweaks

Co-authored-by: Joel Jesudason <62968241+JoelJesudason@users.noreply.github.com>
Co-authored-by: didi <git@d10r.net>

* BNB Chain Support (#925)

ethereum-contracts, js-sdk, sdk-core, subgraph

Co-authored-by: didi <git@d10r.net>

* [SDK-REDUX] Mark on a tracked transaction whether Subgraph polling was successful (#921)

* SDK-Core Subgraph Changes (#917)

* mapping updates
* add missing token property to super token events
* add governanceAddress to superfluid governance event entities
* add TokenStatisticLog entity
* add totalAmountStreamedIn, totalAmountStreamedOut properties to ATS and ATSLog entities
* tests for new properties on ATS
* tests for new TSLog entity
* undo manual accounting for balance
* always use rpc to get balance and update
* add gasPrice to event entities
* code cleanup + add some standards for subgraph indexing functions:
  * prepend `_` to create event/log entity functions: `_createEventNameEventEntity`
  * handler functions should follow format of handleEventName
* minor mapping file structure cleanup - separate to different sections
* sdk core subgraph changes
* add gasPrice test
* add support of log queries to sdk-redux
* token and governanceAddress properly mapped
* governanceAddress and token added

Co-authored-by: Kaspar Kallas <kaspar@superfluid.finance>

* Subgraph Release Branch Conflicts Fix (#934)

* SDK-Core Release Branch Conflicts Fix (#932)

* duplicate removed

Co-authored-by: saflamini <43142465+saflamini@users.noreply.github.com>
Co-authored-by: Sam Flamini <sam_flamini@Sams-MacBook-Air.local>
Co-authored-by: Joshua Trujillo <Jtriley15@gmail.com>
Co-authored-by: Kaspar Kallas <kaspar@superfluid.finance>
Co-authored-by: elvijsTDL <77115130+elvijsTDL@users.noreply.github.com>
Co-authored-by: Miao ZhiCheng <miao@superfluid.finance>
Co-authored-by: Axe <ngmachado@users.noreply.github.com>
Co-authored-by: Didi <git@d10r.net>
Co-authored-by: Mehul Soni <65469737+msoni89@users.noreply.github.com>
Co-authored-by: Sunny Jaycer <62968241+sunnyjaycer@users.noreply.github.com>
Co-authored-by: Joel Jesudason <62968241+JoelJesudason@users.noreply.github.com>
Co-authored-by: Bertrand Juglas <b@juglas.name>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[ETHEREUM-CONTRACTS] Integrate solidity-docgen for dev branch
3 participants