solidity/libsolidity/interface/Natspec.cpp

288 lines
9.3 KiB
C++
Raw Normal View History

2017-05-10 09:54:23 +00:00
/*
2019-02-13 15:56:46 +00:00
This file is part of solidity.
2017-05-10 09:54:23 +00:00
2019-02-13 15:56:46 +00:00
solidity is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
2017-05-10 09:54:23 +00:00
2019-02-13 15:56:46 +00:00
solidity is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
2017-05-10 09:54:23 +00:00
2019-02-13 15:56:46 +00:00
You should have received a copy of the GNU General Public License
along with solidity. If not, see <http://www.gnu.org/licenses/>.
2017-05-10 09:54:23 +00:00
*/
// SPDX-License-Identifier: GPL-3.0
2017-05-10 09:54:23 +00:00
/**
* @author Lefteris <lefteris@ethdev.com>
* @date 2014
* Takes the parsed AST and produces the Natspec documentation:
* https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format
*
* Can generally deal with JSON files
*/
2017-05-10 09:56:21 +00:00
#include <libsolidity/interface/Natspec.h>
2018-12-17 18:24:42 +00:00
2015-10-20 22:21:52 +00:00
#include <libsolidity/ast/AST.h>
2021-02-25 12:57:34 +00:00
#include <boost/algorithm/string.hpp>
2015-10-26 14:13:36 +00:00
using namespace std;
2019-12-11 16:31:36 +00:00
using namespace solidity;
using namespace solidity::frontend;
2017-05-10 09:56:21 +00:00
Json::Value Natspec::userDocumentation(ContractDefinition const& _contractDef)
{
Json::Value doc{Json::objectValue};
doc["version"] = Json::Value(c_natspecVersion);
doc["kind"] = Json::Value("user");
2021-02-03 12:53:39 +00:00
doc["methods"] = Json::objectValue;
auto constructorDefinition(_contractDef.constructor());
if (constructorDefinition)
{
string const value = extractDoc(constructorDefinition->annotation().docTags, "notice");
if (!value.empty())
{
// add the constructor, only if we have any documentation to add
Json::Value user{Json::objectValue};
user["notice"] = Json::Value(value);
2021-02-03 12:53:39 +00:00
doc["methods"]["constructor"] = user;
}
}
string notice = extractDoc(_contractDef.annotation().docTags, "notice");
if (!notice.empty())
doc["notice"] = Json::Value(notice);
2015-08-31 16:44:29 +00:00
for (auto const& it: _contractDef.interfaceFunctions())
2015-10-26 14:13:36 +00:00
if (it.second->hasDeclaration())
{
2020-06-29 12:30:09 +00:00
string value;
2015-10-26 14:13:36 +00:00
if (auto const* f = dynamic_cast<FunctionDefinition const*>(&it.second->declaration()))
2020-06-29 12:30:09 +00:00
value = extractDoc(f->annotation().docTags, "notice");
else if (auto var = dynamic_cast<VariableDeclaration const*>(&it.second->declaration()))
{
solAssert(var->isStateVariable() && var->isPublic(), "");
2020-06-29 12:30:09 +00:00
value = extractDoc(var->annotation().docTags, "notice");
}
if (!value.empty())
// since @notice is the only user tag if missing function should not appear
2021-02-03 12:53:39 +00:00
doc["methods"][it.second->externalSignature()]["notice"] = value;
}
2020-05-25 06:43:57 +00:00
for (auto const& event: uniqueInterfaceEvents(_contractDef))
2020-05-25 06:43:57 +00:00
{
string value = extractDoc(event->annotation().docTags, "notice");
if (!value.empty())
2021-02-03 12:53:39 +00:00
doc["events"][event->functionType(true)->externalSignature()]["notice"] = value;
2020-05-25 06:43:57 +00:00
}
2021-02-03 12:53:39 +00:00
for (auto const& error: _contractDef.interfaceErrors())
{
string value = extractDoc(error->annotation().docTags, "notice");
if (!value.empty())
{
Json::Value errorDoc{Json::objectValue};
2021-02-03 12:53:39 +00:00
errorDoc["notice"] = value;
2022-08-23 17:28:45 +00:00
doc["errors"][error->functionType(true)->externalSignature()].append(std::move(errorDoc));
2021-02-03 12:53:39 +00:00
}
}
return doc;
}
2017-05-10 09:56:21 +00:00
Json::Value Natspec::devDocumentation(ContractDefinition const& _contractDef)
{
2021-02-25 12:57:34 +00:00
Json::Value doc = extractCustomDoc(_contractDef.annotation().docTags);
doc["version"] = Json::Value(c_natspecVersion);
doc["kind"] = Json::Value("dev");
2015-10-26 14:13:36 +00:00
auto author = extractDoc(_contractDef.annotation().docTags, "author");
if (!author.empty())
doc["author"] = author;
auto title = extractDoc(_contractDef.annotation().docTags, "title");
if (!title.empty())
doc["title"] = title;
auto dev = extractDoc(_contractDef.annotation().docTags, "dev");
if (!dev.empty())
doc["details"] = Json::Value(dev);
2021-02-03 12:53:39 +00:00
doc["methods"] = Json::objectValue;
auto constructorDefinition(_contractDef.constructor());
2018-09-18 16:04:11 +00:00
if (constructorDefinition)
{
Json::Value constructor(devDocumentation(constructorDefinition->annotation().docTags));
if (!constructor.empty())
// add the constructor, only if we have any documentation to add
2021-02-03 12:53:39 +00:00
doc["methods"]["constructor"] = constructor;
}
2015-08-31 16:44:29 +00:00
for (auto const& it: _contractDef.interfaceFunctions())
{
2015-10-26 14:13:36 +00:00
if (!it.second->hasDeclaration())
continue;
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
Json::Value jsonReturn = extractReturnParameterDocs(
fun->annotation().docTags,
fun->functionType(false)->returnParameterNames()
);
if (!jsonReturn.empty())
2022-08-23 17:28:45 +00:00
method["returns"] = std::move(jsonReturn);
if (!method.empty())
2022-08-23 17:28:45 +00:00
doc["methods"][it.second->externalSignature()] = std::move(method);
}
}
for (VariableDeclaration const* varDecl: _contractDef.stateVariables())
{
if (auto devDoc = devDocumentation(varDecl->annotation().docTags); !devDoc.empty())
2021-02-03 12:53:39 +00:00
doc["stateVariables"][varDecl->name()] = devDoc;
auto const assignIfNotEmpty = [&](string const& _name, Json::Value const& _content)
{
if (!_content.empty())
doc["stateVariables"][varDecl->name()][_name] = _content;
};
if (varDecl->annotation().docTags.count("return") == 1)
assignIfNotEmpty("return", extractDoc(varDecl->annotation().docTags, "return"));
if (FunctionTypePointer functionType = varDecl->functionType(false))
assignIfNotEmpty("returns", extractReturnParameterDocs(
varDecl->annotation().docTags,
functionType->returnParameterNames()
));
}
for (auto const& event: uniqueInterfaceEvents(_contractDef))
2020-05-25 06:43:57 +00:00
if (auto devDoc = devDocumentation(event->annotation().docTags); !devDoc.empty())
2021-02-03 12:53:39 +00:00
doc["events"][event->functionType(true)->externalSignature()] = devDoc;
for (auto const& error: _contractDef.interfaceErrors())
if (auto devDoc = devDocumentation(error->annotation().docTags); !devDoc.empty())
doc["errors"][error->functionType(true)->externalSignature()].append(devDoc);
return doc;
}
Json::Value Natspec::extractReturnParameterDocs(std::multimap<std::string, DocTag> const& _tags, vector<string> const& _returnParameterNames)
{
Json::Value jsonReturn{Json::objectValue};
auto returnDocs = _tags.equal_range("return");
if (!_returnParameterNames.empty())
{
size_t n = 0;
for (auto i = returnDocs.first; i != returnDocs.second; i++)
{
string paramName = _returnParameterNames.at(n);
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;
}
2017-05-10 09:56:21 +00:00
string Natspec::extractDoc(multimap<string, DocTag> const& _tags, string const& _name)
{
2015-10-26 14:13:36 +00:00
string value;
auto range = _tags.equal_range(_name);
for (auto i = range.first; i != range.second; i++)
value += i->second.content;
return value;
}
2021-02-25 12:57:34 +00:00
Json::Value Natspec::extractCustomDoc(multimap<string, DocTag> const& _tags)
{
std::map<string, string> concatenated;
for (auto const& [tag, value]: _tags)
if (boost::starts_with(tag, "custom"))
concatenated[tag] += value.content;
// We do not want to create an object if there are no custom tags found.
if (concatenated.empty())
return Json::nullValue;
Json::Value result{Json::objectValue};
2021-02-25 12:57:34 +00:00
for (auto& [tag, value]: concatenated)
2022-08-23 17:28:45 +00:00
result[tag] = std::move(value);
2021-02-25 12:57:34 +00:00
return result;
}
2019-02-14 10:37:24 +00:00
Json::Value Natspec::devDocumentation(std::multimap<std::string, DocTag> const& _tags)
{
2021-02-25 12:57:34 +00:00
Json::Value json = extractCustomDoc(_tags);
auto dev = extractDoc(_tags, "dev");
if (!dev.empty())
json["details"] = Json::Value(dev);
auto author = extractDoc(_tags, "author");
if (!author.empty())
json["author"] = author;
Json::Value params(Json::objectValue);
auto paramRange = _tags.equal_range("param");
for (auto i = paramRange.first; i != paramRange.second; ++i)
params[i->second.paramName] = Json::Value(i->second.content);
if (!params.empty())
json["params"] = params;
return json;
}
vector<EventDefinition const*> Natspec::uniqueInterfaceEvents(ContractDefinition const& _contract)
{
auto eventSignature = [](EventDefinition const* _event) -> string {
FunctionType const* functionType = _event->functionType(true);
solAssert(functionType, "");
return functionType->externalSignature();
};
auto compareBySignature =
[&](EventDefinition const* _lhs, EventDefinition const* _rhs) -> bool {
return eventSignature(_lhs) < eventSignature(_rhs);
};
set<EventDefinition const*, decltype(compareBySignature)> uniqueEvents{compareBySignature};
// Insert events defined in the contract first so that in case of a conflict
// they're the ones that get selected.
uniqueEvents += _contract.definedInterfaceEvents();
set<EventDefinition const*, decltype(compareBySignature)> filteredUsedEvents{compareBySignature};
set<string> usedSignatures;
for (EventDefinition const* event: _contract.usedInterfaceEvents())
{
auto&& [eventIt, eventInserted] = filteredUsedEvents.insert(event);
auto&& [signatureIt, signatureInserted] = usedSignatures.insert(eventSignature(event));
if (!signatureInserted)
filteredUsedEvents.erase(eventIt);
}
uniqueEvents += filteredUsedEvents;
return util::convertContainer<vector<EventDefinition const*>>(std::move(uniqueEvents));
}