feat: natspec improvements and run natspec check on CI (#72)

* chore: run natspec-smells as part of CI

* chore: fix natspec issues

.github/workflows/ci.yml

@@ -65,7 +65,7 @@ jobs:
         run: yarn test:integration
 
   lint:
-    name: Lint Commit Messages
+    name: Static Analysis
     runs-on: ubuntu-latest
 
     steps:
@@ -89,4 +89,8 @@ jobs:
       - name: Install dependencies
         run: yarn --frozen-lockfile --network-concurrency 1
 
-      - run: yarn lint:check
+      - name: Run forge-fmt && solhint
+        run: yarn lint:check
+
+      - name: Run natspec-smells
+        run: yarn lint:natspec 2>&1 >/dev/null | grep 'No issues found'

natspec-smells.config.js

@@ -4,5 +4,7 @@
 
 /** @type {import('@defi-wonderland/natspec-smells').Config} */
 module.exports = {
-  include: 'src/**/*.sol'
+  enforceInheritdoc: false,
+  include: 'src/**/*.sol',
+  exclude: 'src/contracts/B(Num|Const).sol',
 };

src/contracts/BCoWFactory.sol

@@ -32,6 +32,7 @@ contract BCoWFactory is BFactory, IBCoWFactory {
 
   /**
    * @dev Deploys a BCoWPool instead of a regular BPool.
+   * @return _pool The deployed BCoWPool
    */
   function _newBPool() internal virtual override returns (IBPool _pool) {
     return new BCoWPool(SOLUTION_SETTLER, APP_DATA);

src/contracts/BFactory.sol

@@ -62,6 +62,7 @@ contract BFactory is IBFactory {
   /**
    * @notice Deploys a new BPool.
    * @dev Internal function to allow overriding in derived contracts.
+   * @return _pool The deployed BPool
    */
   function _newBPool() internal virtual returns (IBPool _pool) {
     return new BPool();

src/contracts/BMath.sol

@@ -19,6 +19,7 @@ contract BMath is BConst, BNum {
    * @param tokenBalanceOut The balance of the output token in the pool
    * @param tokenWeightOut The weight of the output token in the pool
    * @param swapFee The swap fee of the pool
+   * @return spotPrice The spot price of a token in terms of another one
    * @dev Formula:
    * sP = spotPrice
    * bI = tokenBalanceIn                ( bI / wI )         1
@@ -49,6 +50,7 @@ contract BMath is BConst, BNum {
    * @param tokenWeightOut The weight of the output token in the pool
    * @param tokenAmountIn The amount of the input token
    * @param swapFee The swap fee of the pool
+   * @return tokenAmountOut The amount of token out given the amount of token in for a swap
    * @dev Formula:
    * aO = tokenAmountOut
    * bO = tokenBalanceOut
@@ -84,6 +86,7 @@ contract BMath is BConst, BNum {
    * @param tokenWeightOut The weight of the output token in the pool
    * @param tokenAmountOut The amount of the output token
    * @param swapFee The swap fee of the pool
+   * @return tokenAmountIn The amount of token in given the amount of token out for a swap
    * @dev Formula:
    * aI = tokenAmountIn
    * bO = tokenBalanceOut               /  /     bO      \    (wO / wI)      \
@@ -120,6 +123,7 @@ contract BMath is BConst, BNum {
    * @param totalWeight The total weight of the pool
    * @param tokenAmountIn The amount of the input token
    * @param swapFee The swap fee of the pool
+   * @return poolAmountOut The amount of balancer pool tokens that will be minted
    * @dev Formula:
    * pAo = poolAmountOut         /                                              \
    * tAi = tokenAmountIn        ///      /     //    wI \      \\       \     wI \
@@ -163,6 +167,7 @@ contract BMath is BConst, BNum {
    * @param totalWeight The sum of the weight of all tokens in the pool
    * @param poolAmountOut The expected amount of pool tokens
    * @param swapFee The swap fee of the pool
+   * @return tokenAmountIn The amount of token in requred to mint poolAmountIn token pools
    * @dev Formula:
    * tAi = tokenAmountIn              //(pS + pAo)\     /    1    \\
    * pS = poolSupply                 || ---------  | ^ | --------- || * bI - bI
@@ -205,6 +210,8 @@ contract BMath is BConst, BNum {
    * @param totalWeight The total weight of the pool
    * @param poolAmountIn The amount of pool tokens
    * @param swapFee The swap fee of the pool
+   * @return tokenAmountOut The amount of underlying token out from burning
+   * poolAmountIn pool tokens
    * @dev Formula:
    * tAo = tokenAmountOut            /      /                                             \\
    * bO = tokenBalanceOut           /      // pS - (pAi * (1 - eF)) \     /    1    \      \\
@@ -251,6 +258,8 @@ contract BMath is BConst, BNum {
    * @param totalWeight The total weight of the pool
    * @param tokenAmountOut The amount of the output token
    * @param swapFee The swap fee of the pool
+   * @return poolAmountIn The amount of pool tokens to burn in order to receive
+   * `tokeAmountOut` underlying tokens
    * @dev Formula:
    * pAi = poolAmountIn               // /               tAo             \\     / wO \     \
    * bO = tokenBalanceOut            // | bO - -------------------------- |\   | ---- |     \

src/interfaces/IBFactory.sol

@@ -30,9 +30,9 @@ interface IBFactory {
 
   /**
    * @notice Creates a new BPool, assigning the caller as the pool controller
-   * @return pool The new BPool
+   * @return _pool The new BPool
    */
-  function newBPool() external returns (IBPool pool);
+  function newBPool() external returns (IBPool _pool);
 
   /**
    * @notice Sets the BLabs address in the factory