cerc-io/solidity
16
0
Fork 0
mirror of https://github.com/ethereum/solidity synced 2023-10-03 13:03:40 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #7534 from gh1dra/return-multiple-natspec

Browse Source 
Add support for multiple (named) return parameters in Natspec devdoc
This commit is contained in:
chriseth 2019-11-06 21:55:31 +01:00 committed by GitHub
commit d4354a47b7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
29 changed files with 290 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Changelog.md
View File

@ -14,6 +14,7 @@ Breaking changes:
* Syntax: Abstract contracts need to be marked explicitly as abstract by using the ``abstract`` keyword.
* Inline Assembly: Only strict inline assembly is allowed.
* Type checker: Resulting type of exponentiation is equal to the type of the base. Also allow signed types for the base.
* Natspec JSON Interface: Properly support multiple ``@return`` statements in ``@dev`` documentation and enforce named return parameters to be mentioned documentation.
* Source mappings: Add "modifier depth" as a fifth field in the source mappings.
@ -47,7 +48,6 @@ Bugfixes:
* Type Checker: Treat magic variables as unknown identifiers in inline assembly
### 0.5.12 (2019-10-01)
Language Features:

7
docs/060-breaking-changes.rst
View File

@ -66,10 +66,17 @@ This section gives detailed instructions on how to update prior code for every b
* Change ``uint length = array.push(value)`` to ``array.push(value);``. The new length can be
accessed via ``array.length``.
* For every named return parameter in a function's ``@dev`` documentation define a ``@return``
entry which contains the parameter's name as the first word. E.g. if you have function ``f()`` defined
like ``function f() public returns (uint value)`` and a ``@dev`` annotating it, document its return
parameters like so: ``@return value The return value.``. You can mix named and un-named return parameters
documentation so long as the notices are in the order they appear in the tuple return type.
New Features
============
* The :ref:`try/catch statement <try-catch>` allows you to react on failed external calls.
* Natspec supports multiple return parameters in dev documentation, enforcing the same naming check as ``@param``.
* Yul and Inline Assembly have a new statement called ``leave`` that exits the current function.

45
libsolidity/interface/Natspec.cpp
View File

@ -100,15 +100,54 @@ Json::Value Natspec::devDocumentation(ContractDefinition const& _contractDef)
{
Json::Value method(devDocumentation(fun->annotation().docTags));
if (!method.empty())
{
// add the function, only if we have any documentation to add
Json::Value jsonReturn = extractReturnParameterDocs(fun->annotation().docTags, *fun);
if (!jsonReturn.empty())
method["returns"] = jsonReturn;
methods[it.second->externalSignature()] = method;
}
}
}
doc["methods"] = methods;
return doc;
}
Json::Value Natspec::extractReturnParameterDocs(std::multimap<std::string, DocTag> const& _tags, FunctionDefinition const& _functionDef)
{
Json::Value jsonReturn{Json::objectValue};
auto returnDocs = _tags.equal_range("return");
if (!_functionDef.returnParameters().empty())
{
size_t n = 0;
for (auto i = returnDocs.first; i != returnDocs.second; i++)
{
string paramName = _functionDef.returnParameters().at(n)->name();
string content = i->second.content;
if (paramName.empty())
paramName = "_" + std::to_string(n);
else
{
//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);
}
jsonReturn[paramName] = Json::Value(content);
n++;
}
}
return jsonReturn;
}
string Natspec::extractDoc(multimap<string, DocTag> const& _tags, string const& _name)
{
string value;
@ -129,12 +168,6 @@ Json::Value Natspec::devDocumentation(std::multimap<std::string, DocTag> const&
if (!author.empty())
json["author"] = author;
// for constructors, the "return" node will never exist. invalid tags
// will already generate an error within dev::solidity::DocStringAnalyzer.
auto ret = extractDoc(_tags, "return");
if (!ret.empty())
json["return"] = ret;
Json::Value params(Json::objectValue);
auto paramRange = _tags.equal_range("param");
for (auto i = paramRange.first; i != paramRange.second; ++i)

8
libsolidity/interface/Natspec.h
View File

@ -28,6 +28,7 @@
#include <json/json.h>
#include <memory>
#include <string>
#include <libsolidity/ast/AST.h>
namespace dev
{
@ -60,6 +61,13 @@ private:
/// @return A JSON representation
/// of the contract's developer documentation
static Json::Value devDocumentation(std::multimap<std::string, DocTag> const& _tags);
/// Helper-function that will create a json object for the "returns" field for a given function definition.
/// @param _tags docTags that are used.
/// @param _functionDef functionDefinition that is used to determine which return parameters are named.
/// @return A JSON representation
/// of a method's return notice documentation
static Json::Value extractReturnParameterDocs(std::multimap<std::string, DocTag> const& _tags, FunctionDefinition const& _functionDef);
};
} //solidity NS

12
test/compilationTests/MultiSigWallet/MultiSigWallet.sol
View File

@ -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

2
test/compilationTests/MultiSigWallet/MultiSigWalletFactory.sol
View File

@ -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)

2
test/compilationTests/MultiSigWallet/MultiSigWalletWithDailyLimitFactory.sol
View File

@ -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)

10
test/compilationTests/corion/premium.sol
View File

@ -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) {
/*

14
test/compilationTests/corion/token.sol
View File

@ -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) {
/*

2
test/compilationTests/gnosis/Events/CategoricalEvent.sol
View File

@ -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
override

2
test/compilationTests/gnosis/Events/Event.sol
View File

@ -107,7 +107,7 @@ abstract 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

4
test/compilationTests/gnosis/Events/EventFactory.sol
View File

@ -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,

2
test/compilationTests/gnosis/Events/ScalarEvent.sol
View File

@ -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
override

14
test/compilationTests/gnosis/MarketMakers/LMSRMarketMaker.sol
View File

@ -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
override
@ -57,7 +57,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
override
@ -84,7 +84,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
override
@ -110,7 +110,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
@ -131,7 +131,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 The sum of the outcomes
/// @return offset The 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
@ -170,7 +172,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

4
test/compilationTests/gnosis/Markets/Campaign.sol
View File

@ -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)

2
test/compilationTests/gnosis/Markets/CampaignFactory.sol
View File

@ -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,

8
test/compilationTests/gnosis/Markets/StandardMarket.sol
View File

@ -84,7 +84,7 @@ contract StandardMarket is Market {
}
/// @dev Allows market creator to withdraw fees generated by trades
/// @return Fee amount
/// @return fees Fee amount
function withdrawFees()
public
override
@ -101,7 +101,7 @@ contract StandardMarket is Market {
/// @param outcomeTokenIndex Index of the outcome token to buy
/// @param outcomeTokenCount Amount of outcome tokens to buy
/// @param maxCost The maximum cost in collateral tokens to pay for outcome tokens
/// @return Cost in collateral tokens
/// @return cost Cost in collateral tokens
function buy(uint8 outcomeTokenIndex, uint outcomeTokenCount, uint maxCost)
public
override
@ -132,7 +132,7 @@ contract StandardMarket is Market {
/// @param outcomeTokenIndex Index of the outcome token to sell
/// @param outcomeTokenCount Amount of outcome tokens to sell
/// @param minProfit The minimum profit in collateral tokens to earn for outcome tokens
/// @return Profit in collateral tokens
/// @return profit Profit in collateral tokens
function sell(uint8 outcomeTokenIndex, uint outcomeTokenCount, uint minProfit)
public
override
@ -163,7 +163,7 @@ contract StandardMarket is Market {
/// @param outcomeTokenIndex Index of the outcome token to short sell
/// @param outcomeTokenCount Amount of outcome tokens to short sell
/// @param minProfit The minimum profit in collateral tokens to earn for short sold outcome tokens
/// @return Cost to short sell outcome in collateral tokens
/// @return cost Cost to short sell outcome in collateral tokens
function shortSell(uint8 outcomeTokenIndex, uint outcomeTokenCount, uint minProfit)
public
override

2
test/compilationTests/gnosis/Markets/StandardMarketFactory.sol
View File

@ -14,7 +14,7 @@ contract StandardMarketFactory is MarketFactory {
/// @param eventContract Event contract
/// @param marketMaker Market maker contract
/// @param fee Market fee
/// @return Market contract
/// @return market Market contract
function createMarket(Event eventContract, MarketMaker marketMaker, uint24 fee)
public
override

2
test/compilationTests/gnosis/Oracles/CentralizedOracleFactory.sol
View File

@ -16,7 +16,7 @@ contract CentralizedOracleFactory {
*/
/// @dev Creates a new centralized oracle contract
/// @param ipfsHash Hash identifying off chain event description
/// @return Oracle contract
/// @return centralizedOracle Oracle contract
function createCentralizedOracle(bytes memory ipfsHash)
public
returns (CentralizedOracle centralizedOracle)

2
test/compilationTests/gnosis/Oracles/DifficultyOracleFactory.sol
View File

@ -16,7 +16,7 @@ contract DifficultyOracleFactory {
*/
/// @dev Creates a new difficulty oracle contract
/// @param blockNumber Target block number
/// @return Oracle contract
/// @return difficultyOracle Oracle contract
function createDifficultyOracle(uint blockNumber)
public
returns (DifficultyOracle difficultyOracle)

2
test/compilationTests/gnosis/Oracles/FutarchyOracleFactory.sol
View File

@ -50,7 +50,7 @@ contract FutarchyOracleFactory {
/// @param marketMaker Market maker contract
/// @param fee Market fee
/// @param deadline Decision deadline
/// @return Oracle contract
/// @return futarchyOracle Oracle contract
function createFutarchyOracle(
Token collateralToken,
Oracle oracle,

4
test/compilationTests/gnosis/Oracles/MajorityOracle.sol
View File

@ -28,8 +28,8 @@ contract MajorityOracle is Oracle {
}
/// @dev Allows to registers oracles for a majority vote
/// @return Is outcome set?
/// @return Outcome
/// @return outcomeSet Is outcome set?
/// @return outcome Outcome
function getStatusAndOutcome()
public
view

2
test/compilationTests/gnosis/Oracles/MajorityOracleFactory.sol
View File

@ -16,7 +16,7 @@ contract MajorityOracleFactory {
*/
/// @dev Creates a new majority oracle contract
/// @param oracles List of oracles taking part in the majority vote
/// @return Oracle contract
/// @return majorityOracle Oracle contract
function createMajorityOracle(Oracle[] memory oracles)
public
returns (MajorityOracle majorityOracle)

2
test/compilationTests/gnosis/Oracles/SignedMessageOracleFactory.sol
View File

@ -19,7 +19,7 @@ contract SignedMessageOracleFactory {
/// @param v Signature parameter
/// @param r Signature parameter
/// @param s Signature parameter
/// @return Oracle contract
/// @return signedMessageOracle Oracle contract
function createSignedMessageOracle(bytes32 descriptionHash, uint8 v, bytes32 r, bytes32 s)
public
returns (SignedMessageOracle signedMessageOracle)

2
test/compilationTests/gnosis/Oracles/UltimateOracle.sol
View File

@ -126,7 +126,7 @@ contract UltimateOracle is Oracle {
}
/// @dev Withdraws winnings for user
/// @return Winnings
/// @return amount Winnings
function withdraw()
public
returns (uint amount)

2
test/compilationTests/gnosis/Oracles/UltimateOracleFactory.sol
View File

@ -30,7 +30,7 @@ contract UltimateOracleFactory {
/// @param challengePeriod Time to challenge oracle outcome
/// @param challengeAmount Amount to challenge the outcome
/// @param frontRunnerPeriod Time to overbid the front-runner
/// @return Oracle contract
/// @return ultimateOracle Oracle contract
function createUltimateOracle(
Oracle oracle,
Token collateralToken,

4
test/compilationTests/gnosis/Utils/Math.sol
View File

@ -154,7 +154,7 @@ library Math {
/// @dev Returns base 2 logarithm value of given x
/// @param x x
/// @return logarithmic value
/// @return lo logarithmic value
function floorLog2(uint x)
public
pure
@ -175,7 +175,7 @@ library Math {
/// @dev Returns maximum of an array
/// @param nums Numbers to look through
/// @return Maximum number
/// @return max Maximum number
function max(int[] memory nums)
public
pure

10
test/externalTests/solc-js/DAO/Token.sol
View File

@ -44,13 +44,13 @@ abstract contract TokenInterface {
uint256 public totalSupply;
/// @param _owner The address from which the balance will be retrieved
/// @return The balance
/// @return balance The balance
function balanceOf(address _owner) public view returns (uint256 balance);
/// @notice Send `_amount` 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) public returns (bool success);
/// @notice Send `_amount` tokens to `_to` from `_from` on the condition it
@ -58,19 +58,19 @@ abstract contract TokenInterface {
/// @param _from The address of the origin of the transfer
/// @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 transferFrom(address _from, address _to, uint256 _amount) public returns (bool success);
/// @notice `msg.sender` approves `_spender` to spend `_amount` tokens on
/// its behalf
/// @param _spender The address of the account able to transfer the tokens
/// @param _amount The amount of tokens to be approved for transfer
/// @return Whether the approval was successful or not
/// @return success Whether the approval was successful or not
function approve(address _spender, uint256 _amount) public returns (bool success);
/// @param _owner The address of the account owning tokens
/// @param _spender The address of the account able to transfer the tokens
/// @return Amount of remaining tokens of _owner that _spender is allowed
/// @return remaining Amount of remaining tokens of _owner that _spender is allowed
/// to spend
function allowance(
address _owner,

188
test/libsolidity/SolidityNatspecJSON.cpp
View File

@ -365,7 +365,7 @@ BOOST_AUTO_TEST_CASE(dev_return)
/// @param a Documentation for the first parameter starts here.
/// Since it's a really complicated parameter we need 2 lines
/// @param second Documentation for the second parameter
/// @return The result of the multiplication
/// @return d The result of the multiplication
function mul(uint a, uint second) public returns (uint d) { return a * 7 + second; }
}
)";
@ -378,12 +378,15 @@ BOOST_AUTO_TEST_CASE(dev_return)
" \"a\": \"Documentation for the first parameter starts here. Since it's a really complicated parameter we need 2 lines\",\n"
" \"second\": \"Documentation for the second parameter\"\n"
" },\n"
" \"return\": \"The result of the multiplication\"\n"
" \"returns\": {\n"
" \"d\": \"The result of the multiplication\"\n"
" }\n"
" }\n"
"}}";
checkNatspec(sourceCode, "test", natspec, false);
}
BOOST_AUTO_TEST_CASE(dev_return_desc_after_nl)
{
char const* sourceCode = R"(
@ -393,7 +396,7 @@ BOOST_AUTO_TEST_CASE(dev_return_desc_after_nl)
/// Since it's a really complicated parameter we need 2 lines
/// @param second Documentation for the second parameter
/// @return
/// The result of the multiplication
/// d The result of the multiplication
function mul(uint a, uint second) public returns (uint d) {
return a * 7 + second;
}
@ -408,13 +411,157 @@ BOOST_AUTO_TEST_CASE(dev_return_desc_after_nl)
" \"a\": \"Documentation for the first parameter starts here. Since it's a really complicated parameter we need 2 lines\",\n"
" \"second\": \"Documentation for the second parameter\"\n"
" },\n"
" \"return\": \"The result of the multiplication\"\n"
" \"returns\": {\n"
" \"d\": \"The result of the multiplication\"\n"
" }\n"
" }\n"
"}}";
checkNatspec(sourceCode, "test", natspec, false);
}
BOOST_AUTO_TEST_CASE(dev_return_desc_multiple_unamed_mixed)
{
char const* sourceCode = R"(
contract test {
/// @dev Multiplies a number by 7 and adds second parameter
/// @param a Documentation for the first parameter starts here.
/// Since it's a really complicated parameter we need 2 lines
/// @param second Documentation for the second parameter
/// @return The result of the multiplication
/// @return _cookies And cookies with nutella
function mul(uint a, uint second) public returns (uint, uint _cookies) {
uint mul = a * 7;
return (mul, second);
}
}
)";
char const* natspec = "{"
"\"methods\":{"
" \"mul(uint256,uint256)\":{ \n"
" \"details\": \"Multiplies a number by 7 and adds second parameter\",\n"
" \"params\": {\n"
" \"a\": \"Documentation for the first parameter starts here. Since it's a really complicated parameter we need 2 lines\",\n"
" \"second\": \"Documentation for the second parameter\"\n"
" },\n"
" \"returns\": {\n"
" \"_0\": \"The result of the multiplication\",\n"
" \"_cookies\": \"And cookies with nutella\"\n"
" }\n"
" }\n"
"}}";
checkNatspec(sourceCode, "test", natspec, false);
}
BOOST_AUTO_TEST_CASE(dev_return_desc_multiple_unamed_mixed_2)
{
char const* sourceCode = R"(
contract test {
/// @dev Multiplies a number by 7 and adds second parameter
/// @param a Documentation for the first parameter starts here.
/// Since it's a really complicated parameter we need 2 lines
/// @param second Documentation for the second parameter
/// @return _cookies And cookies with nutella
/// @return The result of the multiplication
/// @return _milk And milk with nutella
function mul(uint a, uint second) public returns (uint _cookies, uint, uint _milk) {
uint mul = a * 7;
uint milk = 4;
return (mul, second, milk);
}
}
)";
char const* natspec = "{"
"\"methods\":{"
" \"mul(uint256,uint256)\":{ \n"
" \"details\": \"Multiplies a number by 7 and adds second parameter\",\n"
" \"params\": {\n"
" \"a\": \"Documentation for the first parameter starts here. Since it's a really complicated parameter we need 2 lines\",\n"
" \"second\": \"Documentation for the second parameter\"\n"
" },\n"
" \"returns\": {\n"
" \"_cookies\": \"And cookies with nutella\",\n"
" \"_1\": \"The result of the multiplication\",\n"
" \"_milk\": \"And milk with nutella\"\n"
" }\n"
" }\n"
"}}";
checkNatspec(sourceCode, "test", natspec, false);
}
BOOST_AUTO_TEST_CASE(dev_return_desc_multiple_unamed)
{
char const* sourceCode = R"(
contract test {
/// @dev Multiplies a number by 7 and adds second parameter
/// @param a Documentation for the first parameter starts here.
/// Since it's a really complicated parameter we need 2 lines
/// @param second Documentation for the second parameter
/// @return The result of the multiplication
/// @return And cookies with nutella
function mul(uint a, uint second) public returns (uint, uint) {
uint mul = a * 7;
return (mul, second);
}
}
)";
char const* natspec = "{"
"\"methods\":{"
" \"mul(uint256,uint256)\":{ \n"
" \"details\": \"Multiplies a number by 7 and adds second parameter\",\n"
" \"params\": {\n"
" \"a\": \"Documentation for the first parameter starts here. Since it's a really complicated parameter we need 2 lines\",\n"
" \"second\": \"Documentation for the second parameter\"\n"
" },\n"
" \"returns\": {\n"
" \"_0\": \"The result of the multiplication\",\n"
" \"_1\": \"And cookies with nutella\"\n"
" }\n"
" }\n"
"}}";
checkNatspec(sourceCode, "test", natspec, false);
}
BOOST_AUTO_TEST_CASE(dev_return_desc_multiple)
{
char const* sourceCode = R"(
contract test {
/// @dev Multiplies a number by 7 and adds second parameter
/// @param a Documentation for the first parameter starts here.
/// Since it's a really complicated parameter we need 2 lines
/// @param second Documentation for the second parameter
/// @return d The result of the multiplication
/// @return f And cookies with nutella
function mul(uint a, uint second) public returns (uint d, uint f) {
uint mul = a * 7;
return (mul, second);
}
}
)";
char const* natspec = "{"
"\"methods\":{"
" \"mul(uint256,uint256)\":{ \n"
" \"details\": \"Multiplies a number by 7 and adds second parameter\",\n"
" \"params\": {\n"
" \"a\": \"Documentation for the first parameter starts here. Since it's a really complicated parameter we need 2 lines\",\n"
" \"second\": \"Documentation for the second parameter\"\n"
" },\n"
" \"returns\": {\n"
" \"d\": \"The result of the multiplication\",\n"
" \"f\": \"And cookies with nutella\"\n"
" }\n"
" }\n"
"}}";
checkNatspec(sourceCode, "test", natspec, false);
}
BOOST_AUTO_TEST_CASE(dev_multiline_return)
{
@ -424,7 +571,7 @@ BOOST_AUTO_TEST_CASE(dev_multiline_return)
/// @param a Documentation for the first parameter starts here.
/// Since it's a really complicated parameter we need 2 lines
/// @param second Documentation for the second parameter
/// @return The result of the multiplication
/// @return d The result of the multiplication
/// and cookies with nutella
function mul(uint a, uint second) public returns (uint d) {
return a * 7 + second;
@ -440,7 +587,9 @@ BOOST_AUTO_TEST_CASE(dev_multiline_return)
" \"a\": \"Documentation for the first parameter starts here. Since it's a really complicated parameter we need 2 lines\",\n"
" \"second\": \"Documentation for the second parameter\"\n"
" },\n"
" \"return\": \"The result of the multiplication and cookies with nutella\"\n"
" \"returns\": {\n"
" \"d\": \"The result of the multiplication and cookies with nutella\",\n"
" }\n"
" }\n"
"}}";
@ -456,7 +605,7 @@ BOOST_AUTO_TEST_CASE(dev_multiline_comment)
* @param a Documentation for the first parameter starts here.
* Since it's a really complicated parameter we need 2 lines
* @param second Documentation for the second parameter
* @return The result of the multiplication
* @return d The result of the multiplication
* and cookies with nutella
*/
function mul(uint a, uint second) public returns (uint d) {
@ -473,13 +622,30 @@ BOOST_AUTO_TEST_CASE(dev_multiline_comment)
" \"a\": \"Documentation for the first parameter starts here. Since it's a really complicated parameter we need 2 lines\",\n"
" \"second\": \"Documentation for the second parameter\"\n"
" },\n"
" \"return\": \"The result of the multiplication and cookies with nutella\"\n"
" \"returns\": {\n"
" \"d\": \"The result of the multiplication and cookies with nutella\",\n"
" }\n"
" }\n"
"}}";
checkNatspec(sourceCode, "test", natspec, false);
}
BOOST_AUTO_TEST_CASE(dev_documenting_no_return_paramname)
{
char const* sourceCode = R"(
contract test {
/// @dev Multiplies a number by 7 and adds second parameter
/// @param a Documentation for the first parameter
/// @param second Documentation for the second parameter
/// @return
function mul(uint a, uint second) public returns (uint d) { return a * 7 + second; }
}
)";
expectNatspecError(sourceCode);
}
BOOST_AUTO_TEST_CASE(dev_contract_no_doc)
{
char const* sourceCode = R"(
@ -777,7 +943,7 @@ BOOST_AUTO_TEST_CASE(dev_constructor_and_function)
/// @param a Documentation for the first parameter starts here.
/// Since it's a really complicated parameter we need 2 lines
/// @param second Documentation for the second parameter
/// @return The result of the multiplication
/// @return d The result of the multiplication
/// and cookies with nutella
function mul(uint a, uint second) public returns(uint d) {
return a * 7 + second;
@ -793,7 +959,9 @@ BOOST_AUTO_TEST_CASE(dev_constructor_and_function)
"a" : "Documentation for the first parameter starts here. Since it's a really complicated parameter we need 2 lines",
"second" : "Documentation for the second parameter"
},
"return" : "The result of the multiplication and cookies with nutella"
"returns" : {
"d": "The result of the multiplication and cookies with nutella"
}
},
"constructor" : {
"author" : "Alex",