Completed SwapsExternal review

contracts/modules/LoanMaintenance.sol

@@ -42,7 +42,9 @@ contract LoanMaintenance is LoanOpeningsEvents, LoanMaintenanceEvents, VaultCont
 		uint256 maxSeizable;
 	}
 
-	/// @notice Empty public constructor.
+	/**
+	 * @notice Empty public constructor.
+	 * */
 	constructor() public {}
 
 	/**

contracts/modules/LoanSettings.sol

@@ -18,6 +18,9 @@ import "../events/LoanSettingsEvents.sol";
  * This contract contains functions to get and set loan parameters.
  * */
 contract LoanSettings is State, LoanSettingsEvents {
+	/**
+	 * @notice Empty public constructor.
+	 * */
 	constructor() public {}
 
 	/**
@@ -50,9 +53,7 @@ contract LoanSettings is State, LoanSettingsEvents {
 	 *
 	 * @return loanParamsIdList The array of loan parameters IDs.
 	 * */
-	function setupLoanParams(
-		LoanParams[] calldata loanParamsList
-	) external returns (bytes32[] memory loanParamsIdList) {
+	function setupLoanParams(LoanParams[] calldata loanParamsList) external returns (bytes32[] memory loanParamsIdList) {
 		loanParamsIdList = new bytes32[](loanParamsList.length);
 		for (uint256 i = 0; i < loanParamsList.length; i++) {
 			loanParamsIdList[i] = _setupLoanParams(loanParamsList[i]);

contracts/modules/SwapsExternal.sol

@@ -11,18 +11,54 @@ import "../mixins/VaultController.sol";
 import "../swaps/SwapsUser.sol";
 import "../swaps/ISwapsImpl.sol";
 
+/**
+ * @title Swaps External contract.
+ *
+ * @notice This contract code comes from bZx. bZx is a protocol for tokenized
+ * margin trading and lending https://bzx.network similar to the dYdX protocol.
+ *
+ * This contract contains functions to calculate and execute swaps.
+ * */
 contract SwapsExternal is VaultController, SwapsUser {
+	/**
+	 * @notice Empty public constructor.
+	 * */
 	constructor() public {}
 
+	/**
+	 * @notice Fallback function is to react to receiving value (rBTC).
+	 * */
 	function() external {
 		revert("fallback not allowed");
 	}
 
+	/**
+	 * @notice Set function selectors on target contract.
+	 *
+	 * @param target The address of the target contract.
+	 * */
 	function initialize(address target) external onlyOwner {
 		_setTarget(this.swapExternal.selector, target);
 		_setTarget(this.getSwapExpectedReturn.selector, target);
 	}
 
+	/**
+	 * @notice Perform a swap w/ tokens or rBTC as source currency.
+	 *
+	 * @dev External wrapper that calls SwapsUser::_swapsCall
+	 * after turning potential incoming rBTC into wrBTC tokens.
+	 *
+	 * @param sourceToken The address of the source token instance.
+	 * @param destToken The address of the destiny token instance.
+	 * @param receiver The address of the recipient account.
+	 * @param returnToSender The address of the sender account.
+	 * @param sourceTokenAmount The amount of source tokens.
+	 * @param requiredDestTokenAmount The amount of required destiny tokens.
+	 * @param swapData Additional swap data (not in use yet).
+	 *
+	 * @return destTokenAmountReceived The amount of destiny tokens sent.
+	 * @return sourceTokenAmountUsed The amount of source tokens spent.
+	 * */
 	function swapExternal(
 		address sourceToken,
 		address destToken,
@@ -34,44 +70,60 @@ contract SwapsExternal is VaultController, SwapsUser {
 	) external payable nonReentrant returns (uint256 destTokenAmountReceived, uint256 sourceTokenAmountUsed) {
 		require(sourceTokenAmount != 0, "sourceTokenAmount == 0");
 
+		/// @dev Get payed value, be it rBTC or tokenized.
 		if (msg.value != 0) {
 			if (sourceToken == address(0)) {
 				sourceToken = address(wrbtcToken);
 			}
 			require(sourceToken == address(wrbtcToken), "sourceToken mismatch");
 			require(msg.value == sourceTokenAmount, "sourceTokenAmount mismatch");
+
+			/// @dev Update wrBTC balance for this contract.
 			wrbtcToken.deposit.value(sourceTokenAmount)();
 		} else {
+			/// @dev Transfer tokens from sender to this contract.
 			IERC20(sourceToken).safeTransferFrom(msg.sender, address(this), sourceTokenAmount);
 		}
 
+		/// @dev Perform the swap w/ tokens.
 		(destTokenAmountReceived, sourceTokenAmountUsed) = _swapsCall(
 			[
 				sourceToken,
 				destToken,
 				receiver,
 				returnToSender,
-				msg.sender // user
+				msg.sender /// user
 			],
 			[
-				sourceTokenAmount, // minSourceTokenAmount
-				sourceTokenAmount, // maxSourceTokenAmount
+				sourceTokenAmount, /// minSourceTokenAmount
+				sourceTokenAmount, /// maxSourceTokenAmount
 				requiredDestTokenAmount
 			],
-			0, // loanId (not tied to a specific loan)
-			false, // bypassFee
+			0, /// loanId (not tied to a specific loan)
+			false, /// bypassFee
 			swapData
 		);
 
 		emit ExternalSwap(
-			msg.sender, // user
+			msg.sender, /// user
 			sourceToken,
 			destToken,
 			sourceTokenAmountUsed,
 			destTokenAmountReceived
 		);
 	}
 
+	/**
+	 * @notice Get the swap expected return value.
+	 *
+	 * @dev External wrapper that calls SwapsUser::_swapsExpectedReturn
+	 *
+	 * @param sourceToken The address of the source token instance.
+	 * @param destToken The address of the destiny token instance.
+	 * @param sourceTokenAmount The amount of source tokens.
+	 *
+	 * @return 
+	 * */
 	function getSwapExpectedReturn(
 		address sourceToken,
 		address destToken,