fix: addresses #2 and #3

src/ReservoirPriceOracle.sol

@@ -83,6 +83,7 @@ contract ReservoirPriceOracle is IPriceOracle, Owned(msg.sender), ReentrancyGuar
 
     // IPriceOracle
 
+    /// @inheritdoc IPriceOracle
     function name() external pure returns (string memory) {
         return "RESERVOIR PRICE ORACLE";
     }
@@ -103,6 +104,13 @@ contract ReservoirPriceOracle is IPriceOracle, Owned(msg.sender), ReentrancyGuar
 
     // price update related functions
 
+    /// @notice Returns the defined route between a given pair of tokens if there is one.
+    /// @param aToken0 Address of the lower token.
+    /// @param aToken1 Address of the higher token.
+    /// @return rRoute An array containing the tokens that make up the route.
+    /// Contains two elements if it is a simple route (A->B),
+    /// Contains three elements if it is a 2 hop route (A->B->C) and so on.
+    /// Returns an empty array if there is no route, or if the arg tokens are not sorted.
     function route(address aToken0, address aToken1) external view returns (address[] memory rRoute) {
         (rRoute,,,) = _getRouteDecimalDifferencePrice(aToken0, aToken1);
     }
@@ -543,6 +551,9 @@ contract ReservoirPriceOracle is IPriceOracle, Owned(msg.sender), ReentrancyGuar
         emit Route(aToken0, aToken1, aRoute);
     }
 
+    /// @notice Clears the defined route and the corresponding storage slots.
+    /// @param aToken0 Address of the lower token.
+    /// @param aToken1 Address of the higher token.
     function clearRoute(address aToken0, address aToken1) external onlyOwner {
         _validateTokens(aToken0, aToken1);
 

src/interfaces/IPriceOracle.sol

@@ -2,23 +2,26 @@
 pragma solidity ^0.8.0;
 
 interface IPriceOracle {
+    /// @notice Get the name of the oracle.
+    /// @return The name of the oracle.
     function name() external view returns (string memory);
 
-    /// @notice Returns the quote for a given amount of base asset in quote asset.
-    /// @param amount The amount of base asset.
-    /// @param base The address of the base asset.
-    /// @param quote The address of the quote asset.
-    /// @return out The quote amount in quote asset.
-    function getQuote(uint256 amount, address base, address quote) external view returns (uint256 out);
+    /// @notice One-sided price: How much quote token you would get for inAmount of base token, assuming no price
+    /// spread.
+    /// @param inAmount The amount of `base` to convert.
+    /// @param base The token that is being priced.
+    /// @param quote The token that is the unit of account.
+    /// @return outAmount The amount of `quote` that is equivalent to `inAmount` of `base`.
+    function getQuote(uint256 inAmount, address base, address quote) external view returns (uint256 outAmount);
 
-    /// @notice Returns the bid and ask quotes for a given amount of base asset in quote asset.
-    /// @param amount The amount of base asset.
-    /// @param base The address of the base asset.
-    /// @param quote The address of the quote asset.
-    /// @return bidOut The bid quote amount in quote asset.
-    /// @return askOut The ask quote amount in quote asset.
-    function getQuotes(uint256 amount, address base, address quote)
+    /// @notice Two-sided price: How much quote token you would get/spend for selling/buying inAmount of base token.
+    /// @param inAmount The amount of `base` to convert.
+    /// @param base The token that is being priced.
+    /// @param quote The token that is the unit of account.
+    /// @return bidOutAmount The amount of `quote` you would get for selling `inAmount` of `base`.
+    /// @return askOutAmount The amount of `quote` you would spend for buying `inAmount` of `base`.
+    function getQuotes(uint256 inAmount, address base, address quote)
         external
         view
-        returns (uint256 bidOut, uint256 askOut);
+        returns (uint256 bidOutAmount, uint256 askOutAmount);
 }