Give unamed parameters unique keys and update tests to new spec

Changelog.md

@@ -1,3 +1,16 @@
+### 0.6.0 (unreleased)
+
+Language Features:
+
+
+Compiler Features:
+ * Natspec JSON Interface: Support multiple ``@return`` statements in dev documentation to behave like named parameters.
+
+
+Bugfixes:
+
+
+
 ### 0.5.13 (unreleased)
 
 Language Features:

libsolidity/interface/Natspec.cpp

@@ -99,37 +99,36 @@ Json::Value Natspec::devDocumentation(ContractDefinition const& _contractDef)
 		if (auto fun = dynamic_cast<FunctionDefinition const*>(&it.second->declaration()))
 		{
 			Json::Value method(devDocumentation(fun->annotation().docTags));
-
-			// add the function, only if we have any documentation to add
 			if (!method.empty())
 			{
+				// add the function, only if we have any documentation to add
 				Json::Value ret(Json::objectValue);
 
-				// for constructors, the "return" node will never exist. invalid tags
-				// will already generate an error within dev::solidity::DocStringAnalyzer.
 				auto returnParams = fun->returnParameters();
 				auto returnDoc = fun->annotation().docTags.equal_range("return");
 
 				if (!returnParams.empty())
 				{
-					// if there is no name then append subsequent return notices like previous behavior
-					string value;
 					unsigned int n = 0;
 					for (auto i = returnDoc.first; i != returnDoc.second; i++)
 					{
 						string paramName = returnParams.at(n)->name();
+						string content = i->second.content;
 
-						if (!paramName.empty() && returnParams.size() != 1)
+						if (paramName.empty())
 						{
-							ret[paramName] = Json::Value(i->second.content);
-							n++;
+							paramName = "_" + std::to_string(n+1);
 						}
-
 						else
 						{
-							value += i->second.content;
-							method["return"] = Json::Value(value);
+							//check to make sure the first word of the doc str is the same as the return name
+							auto nameEndPos = content.find_first_of(" \t");
+							solAssert(content.substr(0, nameEndPos) == paramName, "No return param name given: " + paramName);
+							content = content.substr(nameEndPos+1);
 						}
+
+						ret[paramName] = Json::Value(content);
+						n++;
 					}
 				}
 
@@ -138,7 +137,7 @@ Json::Value Natspec::devDocumentation(ContractDefinition const& _contractDef)
 
 				methods[it.second->externalSignature()] = method;
 			}
-	  	}
+		}
 	}
 
 	doc["methods"] = methods;

test/compilationTests/MultiSigWallet/MultiSigWallet.sol

@@ -184,7 +184,7 @@ contract MultiSigWallet {
     /// @param destination Transaction target address.
     /// @param value Transaction ether value.
     /// @param data Transaction data payload.
-    /// @return Returns transaction ID.
+    /// @return transactionId Returns transaction ID.
     function submitTransaction(address destination, uint value, bytes memory data)
         public
         returns (uint transactionId)
@@ -258,7 +258,7 @@ contract MultiSigWallet {
     /// @param destination Transaction target address.
     /// @param value Transaction ether value.
     /// @param data Transaction data payload.
-    /// @return Returns transaction ID.
+    /// @return transactionId Returns transaction ID.
     function addTransaction(address destination, uint value, bytes memory data)
         internal
         notNull(destination)
@@ -280,7 +280,7 @@ contract MultiSigWallet {
      */
     /// @dev Returns number of confirmations of a transaction.
     /// @param transactionId Transaction ID.
-    /// @return Number of confirmations.
+    /// @return count Number of confirmations.
     function getConfirmationCount(uint transactionId)
         public
         view
@@ -294,7 +294,7 @@ contract MultiSigWallet {
     /// @dev Returns total number of transactions after filers are applied.
     /// @param pending Include pending transactions.
     /// @param executed Include executed transactions.
-    /// @return Total number of transactions after filters are applied.
+    /// @return count Total number of transactions after filters are applied.
     function getTransactionCount(bool pending, bool executed)
         public
         view
@@ -318,7 +318,7 @@ contract MultiSigWallet {
 
     /// @dev Returns array with owner addresses, which confirmed transaction.
     /// @param transactionId Transaction ID.
-    /// @return Returns array of owner addresses.
+    /// @return _confirmations Returns array of owner addresses.
     function getConfirmations(uint transactionId)
         public
         view
@@ -342,7 +342,7 @@ contract MultiSigWallet {
     /// @param to Index end position of transaction array.
     /// @param pending Include pending transactions.
     /// @param executed Include executed transactions.
-    /// @return Returns array of transaction IDs.
+    /// @return _transactionIds Returns array of transaction IDs.
     function getTransactionIds(uint from, uint to, bool pending, bool executed)
         public
         view

test/compilationTests/MultiSigWallet/MultiSigWalletFactory.sol

@@ -10,7 +10,7 @@ contract MultiSigWalletFactory is Factory {
     /// @dev Allows verified creation of multisignature wallet.
     /// @param _owners List of initial owners.
     /// @param _required Number of required confirmations.
-    /// @return Returns wallet address.
+    /// @return wallet Returns wallet address.
     function create(address[] memory _owners, uint _required)
         public
         returns (address wallet)

test/compilationTests/MultiSigWallet/MultiSigWalletWithDailyLimitFactory.sol

@@ -11,7 +11,7 @@ contract MultiSigWalletWithDailyLimitFactory is Factory {
     /// @param _owners List of initial owners.
     /// @param _required Number of required confirmations.
     /// @param _dailyLimit Amount in wei, which can be withdrawn without confirmations on a daily basis.
-    /// @return Returns wallet address.
+    /// @return wallet Returns wallet address.
     function create(address[] memory _owners, uint _required, uint _dailyLimit)
         public
         returns (address wallet)

test/compilationTests/corion/premium.sol

@@ -84,7 +84,7 @@ contract premium is module, safeMath {
      * @param spender The address of the account able to transfer the tokens
      * @param amount The amount of tokens to be approved for transfer
      * @param nonce The transaction count of the authorised address
-     * @return True if the approval was successful
+     * @return success True if the approval was successful
      */
     function approve(address spender, uint256 amount, uint256 nonce) isReady external returns (bool success) {
         /*
@@ -106,7 +106,7 @@ contract premium is module, safeMath {
      * @param amount The amount of tokens to be approved for transfer
      * @param nonce The transaction count of the authorised address
      * @param extraData Data to give forward to the receiver
-     * @return True if the approval was successful
+     * @return success True if the approval was successful
      */
     function approveAndCall(address spender, uint256 amount, uint256 nonce, bytes calldata extraData) isReady external returns (bool success) {
         /*
@@ -159,7 +159,7 @@ contract premium is module, safeMath {
      * @notice Send `amount` Corion tokens to `to` from `msg.sender`
      * @param to The address of the recipient
      * @param amount The amount of tokens to be transferred
-     * @return Whether the transfer was successful or not
+     * @return success Whether the transfer was successful or not
      */
     function transfer(address to, uint256 amount) isReady external returns (bool success) {
         /*
@@ -187,7 +187,7 @@ contract premium is module, safeMath {
      * @param from The address holding the tokens being transferred
      * @param to The address of the recipient
      * @param amount The amount of tokens to be transferred
-     * @return True if the transfer was successful
+     * @return success True if the transfer was successful
      */
     function transferFrom(address from, address to, uint256 amount) isReady external returns (bool success) {
         /*
@@ -224,7 +224,7 @@ contract premium is module, safeMath {
      * @param to The contract address of the recipient
      * @param amount The amount of tokens to be transferred
      * @param extraData Data to give forward to the receiver
-     * @return Whether the transfer was successful or not
+     * @return success Whether the transfer was successful or not
      */
     function transfer(address to, uint256 amount, bytes calldata extraData) isReady external returns (bool success) {
         /*

test/compilationTests/corion/token.sol

@@ -99,7 +99,7 @@ contract token is safeMath, module, announcementTypes {
      * @param spender The address of the account able to transfer the tokens
      * @param amount The amount of tokens to be approved for transfer
      * @param nonce The transaction count of the authorised address
-     * @return True if the approval was successful
+     * @return success True if the approval was successful
      */
     function approve(address spender, uint256 amount, uint256 nonce) isReady external returns (bool success) {
         /*
@@ -121,7 +121,7 @@ contract token is safeMath, module, announcementTypes {
      * @param amount The amount of tokens to be approved for transfer
      * @param nonce The transaction count of the authorised address
      * @param extraData Data to give forward to the receiver
-     * @return True if the approval was successful
+     * @return success True if the approval was successful
      */
     function approveAndCall(address spender, uint256 amount, uint256 nonce, bytes calldata extraData) isReady external returns (bool success) {
         /*
@@ -174,7 +174,7 @@ contract token is safeMath, module, announcementTypes {
      * @notice Send `amount` Corion tokens to `to` from `msg.sender`
      * @param to The address of the recipient
      * @param amount The amount of tokens to be transferred
-     * @return Whether the transfer was successful or not
+     * @return success Whether the transfer was successful or not
      */
     function transfer(address to, uint256 amount) isReady external returns (bool success) {
         /*
@@ -202,7 +202,7 @@ contract token is safeMath, module, announcementTypes {
      * @param from The address holding the tokens being transferred
      * @param to The address of the recipient
      * @param amount The amount of tokens to be transferred
-     * @return True if the transfer was successful
+     * @return success True if the transfer was successful
      */
     function transferFrom(address from, address to, uint256 amount) isReady external returns (bool success) {
         /*
@@ -239,7 +239,7 @@ contract token is safeMath, module, announcementTypes {
      * @param from The address holding the tokens being transferred
      * @param to The address of the recipient
      * @param amount The amount of tokens to be transferred
-     * @return True if the transfer was successful
+     * @return success True if the transfer was successful
      */
     function transferFromByModule(address from, address to, uint256 amount, bool fee) isReady external returns (bool success) {
         /*
@@ -265,7 +265,7 @@ contract token is safeMath, module, announcementTypes {
      * @param to The contract address of the recipient
      * @param amount The amount of tokens to be transferred
      * @param extraData Data to give forward to the receiver
-     * @return Whether the transfer was successful or not
+     * @return success Whether the transfer was successful or not
      */
     function transfer(address to, uint256 amount, bytes calldata extraData) isReady external returns (bool success) {
         /*
@@ -341,7 +341,7 @@ contract token is safeMath, module, announcementTypes {
      * @notice Transaction fee will be deduced from `owner` for transacting `value`
      * @param owner The address where will the transaction fee deduced
      * @param value The base for calculating the fee
-     * @return True if the transfer was successful
+     * @return success True if the transfer was successful
      */
     function processTransactionFee(address owner, uint256 value) isReady external returns (bool success) {
         /*

test/compilationTests/gnosis/Events/CategoricalEvent.sol

@@ -25,7 +25,7 @@ contract CategoricalEvent is Event {
     }
 
     /// @dev Exchanges sender's winning outcome tokens for collateral tokens
-    /// @return Sender's winnings
+    /// @return winnings Sender's winnings
     function redeemWinnings()
         public
         returns (uint winnings)

test/compilationTests/gnosis/Events/Event.sol

@@ -107,7 +107,7 @@ contract Event {
     }
 
     /// @dev Returns the amount of outcome tokens held by owner
-    /// @return Outcome token distribution
+    /// @return outcomeTokenDistribution Outcome token distribution
     function getOutcomeTokenDistribution(address owner)
         public
         view

test/compilationTests/gnosis/Events/EventFactory.sol

@@ -26,7 +26,7 @@ contract EventFactory {
     /// @param collateralToken Tokens used as collateral in exchange for outcome tokens
     /// @param oracle Oracle contract used to resolve the event
     /// @param outcomeCount Number of event outcomes
-    /// @return Event contract
+    /// @return eventContract Event contract
     function createCategoricalEvent(
         Token collateralToken,
         Oracle oracle,
@@ -53,7 +53,7 @@ contract EventFactory {
     /// @param oracle Oracle contract used to resolve the event
     /// @param lowerBound Lower bound for event outcome
     /// @param upperBound Lower bound for event outcome
-    /// @return Event contract
+    /// @return eventContract Event contract
     function createScalarEvent(
         Token collateralToken,
         Oracle oracle,

test/compilationTests/gnosis/Events/ScalarEvent.sol

@@ -44,7 +44,7 @@ contract ScalarEvent is Event {
     }
 
     /// @dev Exchanges sender's winning outcome tokens for collateral tokens
-    /// @return Sender's winnings
+    /// @return winnings Sender's winnings
     function redeemWinnings()
         public
         returns (uint winnings)

test/compilationTests/gnosis/MarketMakers/LMSRMarketMaker.sol

@@ -21,7 +21,7 @@ contract LMSRMarketMaker is MarketMaker {
     /// @param market Market contract
     /// @param outcomeTokenIndex Index of outcome to buy
     /// @param outcomeTokenCount Number of outcome tokens to buy
-    /// @return Cost
+    /// @return cost Cost
     function calcCost(Market market, uint8 outcomeTokenIndex, uint outcomeTokenCount)
         public
         view
@@ -56,7 +56,7 @@ contract LMSRMarketMaker is MarketMaker {
     /// @param market Market contract
     /// @param outcomeTokenIndex Index of outcome to sell
     /// @param outcomeTokenCount Number of outcome tokens to sell
-    /// @return Profit
+    /// @return profit Profit
     function calcProfit(Market market, uint8 outcomeTokenIndex, uint outcomeTokenCount)
         public
         view
@@ -82,7 +82,7 @@ contract LMSRMarketMaker is MarketMaker {
     /// @dev Returns marginal price of an outcome
     /// @param market Market contract
     /// @param outcomeTokenIndex Index of outcome to determine marginal price of
-    /// @return Marginal price of an outcome as a fixed point number
+    /// @return price Marginal price of an outcome as a fixed point number
     function calcMarginalPrice(Market market, uint8 outcomeTokenIndex)
         public
         view
@@ -107,7 +107,7 @@ contract LMSRMarketMaker is MarketMaker {
     /// @param logN Logarithm of the number of outcomes
     /// @param netOutcomeTokensSold Net outcome tokens sold by market
     /// @param funding Initial funding for market
-    /// @return Cost level
+    /// @return costLevel Cost level
     function calcCostLevel(int logN, int[] memory netOutcomeTokensSold, uint funding)
         private
         view
@@ -128,7 +128,9 @@ contract LMSRMarketMaker is MarketMaker {
     /// @param netOutcomeTokensSold Net outcome tokens sold by market
     /// @param funding Initial funding for market
     /// @param outcomeIndex Index of exponential term to extract (for use by marginal price function)
-    /// @return A result structure composed of the sum, the offset used, and the summand associated with the supplied index
+    /// @return sum of the outcomes
+    /// @return offset that is used for all
+    /// @return outcomeExpTerm the summand associated with the supplied index
     function sumExpOffset(int logN, int[] memory netOutcomeTokensSold, uint funding, uint8 outcomeIndex)
         private
         view
@@ -167,7 +169,7 @@ contract LMSRMarketMaker is MarketMaker {
     ///      number of collateral tokens (which is the same as the number of outcome tokens the
     ///      market created) subtracted by the quantity of that token held by the market.
     /// @param market Market contract
-    /// @return Net outcome tokens sold by market
+    /// @return quantities Net outcome tokens sold by market
     function getNetOutcomeTokensSold(Market market)
         private
         view

test/compilationTests/gnosis/Markets/Campaign.sol

@@ -115,7 +115,7 @@ contract Campaign {
     }
 
     /// @dev Withdraws refund amount
-    /// @return Refund amount
+    /// @return refundAmount Refund amount
     function refund()
         public
         timedTransitions
@@ -162,7 +162,7 @@ contract Campaign {
     }
 
     /// @dev Allows to withdraw fees from campaign contract to contributor
-    /// @return Fee amount
+    /// @return fees Fee amount
     function withdrawFees()
         public
         atStage(Stages.MarketClosed)

test/compilationTests/gnosis/Markets/CampaignFactory.sol

@@ -21,7 +21,7 @@ contract CampaignFactory {
     /// @param fee Market fee
     /// @param funding Initial funding for market
     /// @param deadline Campaign deadline
-    /// @return Market contract
+    /// @return campaign Market contract
     function createCampaigns(
         Event eventContract,
         MarketFactory marketFactory,