Browse Source

Separate user and dev natspec documentation

- plus other small changes according to the spec
cl-refactor
Lefteris Karapetsas 10 years ago
parent
commit
994e891078
  1. 23
      libsolidity/CompilerStack.cpp
  2. 10
      libsolidity/CompilerStack.h
  3. 2
      solc/main.cpp
  4. 37
      test/solidityNatspecJSON.cpp

23
libsolidity/CompilerStack.cpp

@ -123,13 +123,13 @@ string const& CompilerStack::getInterface()
return m_interface;
}
string const& CompilerStack::getDocumentation()
string const& CompilerStack::getUserDocumentation()
{
Json::StyledWriter writer;
if (!m_parseSuccessful)
BOOST_THROW_EXCEPTION(CompilerError() << errinfo_comment("Parsing was not successful."));
if (m_documentation.empty())
if (m_userDocumentation.empty())
{
Json::Value doc;
Json::Value methods(Json::objectValue);
@ -140,14 +140,27 @@ string const& CompilerStack::getDocumentation()
auto strPtr = f->getDocumentation();
if (strPtr)
{
user["user"] = Json::Value(*strPtr);
user["notice"] = Json::Value(*strPtr);
methods[f->getName()] = user;
}
}
doc["methods"] = methods;
m_documentation = writer.write(doc);
m_userDocumentation = writer.write(doc);
}
return m_documentation;
return m_userDocumentation;
}
string const& CompilerStack::getDevDocumentation()
{
Json::StyledWriter writer;
if (!m_parseSuccessful)
BOOST_THROW_EXCEPTION(CompilerError() << errinfo_comment("Parsing was not successful."));
if (m_devDocumentation.empty())
{
// TODO
}
return m_devDocumentation;
}
bytes CompilerStack::staticCompile(std::string const& _sourceCode, bool _optimize)

10
libsolidity/CompilerStack.h

@ -62,9 +62,12 @@ public:
/// Returns a string representing the contract interface in JSON.
/// Prerequisite: Successful call to parse or compile.
std::string const& getInterface();
/// Returns a string representing the contract documentation in JSON.
/// Returns a string representing the contract's user documentation in JSON.
/// Prerequisite: Successful call to parse or compile.
std::string const& getDocumentation();
std::string const& getUserDocumentation();
/// Returns a string representing the contract's developer documentation in JSON.
/// Prerequisite: Successful call to parse or compile.
std::string const& getDevDocumentation();
/// Returns the previously used scanner, useful for counting lines during error reporting.
Scanner const& getScanner() const { return *m_scanner; }
@ -80,7 +83,8 @@ private:
std::shared_ptr<ContractDefinition> m_contractASTNode;
bool m_parseSuccessful;
std::string m_interface;
std::string m_documentation;
std::string m_userDocumentation;
std::string m_devDocumentation;
std::shared_ptr<Compiler> m_compiler;
bytes m_bytecode;
};

2
solc/main.cpp

@ -136,7 +136,7 @@ int main(int argc, char** argv)
cout << eth::disassemble(compiler.getBytecode()) << endl;
cout << "Binary: " << toHex(compiler.getBytecode()) << endl;
cout << "Interface specification: " << compiler.getInterface() << endl;
cout << "Natspec documentation: " << compiler.getDocumentation() << endl;
cout << "Natspec user documentation: " << compiler.getUserDocumentation() << endl;
return 0;
}

37
test/solidityNatspecJSON.cpp

@ -35,8 +35,11 @@ namespace test
class DocumentationChecker
{
public:
void checkNatspec(std::string const& _code, std::string const& _expectedDocumentationString)
void checkNatspec(std::string const& _code,
std::string const& _expectedDocumentationString,
bool _userDocumentation)
{
std::string generatedDocumentationString;
try
{
m_compilerStack.parse(_code);
@ -50,7 +53,11 @@ public:
msg += *extra;
BOOST_FAIL(msg);
}
auto generatedDocumentationString = m_compilerStack.getDocumentation();
if (_userDocumentation)
generatedDocumentationString = m_compilerStack.getUserDocumentation();
else
generatedDocumentationString = m_compilerStack.getDevDocumentation();
Json::Value generatedDocumentation;
m_reader.parse(generatedDocumentationString, generatedDocumentation);
Json::Value expectedDocumentation;
@ -67,7 +74,7 @@ private:
BOOST_FIXTURE_TEST_SUITE(SolidityNatspecJSON, DocumentationChecker)
BOOST_AUTO_TEST_CASE(basic_test)
BOOST_AUTO_TEST_CASE(user_basic_test)
{
char const* sourceCode = "contract test {\n"
" /// Multiplies `a` by 7\n"
@ -76,13 +83,13 @@ BOOST_AUTO_TEST_CASE(basic_test)
char const* natspec = "{"
"\"methods\":{"
" \"mul\":{ \"user\": \" Multiplies `a` by 7\"}"
" \"mul\":{ \"notice\": \" Multiplies `a` by 7\"}"
"}}";
checkNatspec(sourceCode, natspec);
checkNatspec(sourceCode, natspec, true);
}
BOOST_AUTO_TEST_CASE(multiline_comment)
BOOST_AUTO_TEST_CASE(user_multiline_comment)
{
char const* sourceCode = "contract test {\n"
" /// Multiplies `a` by 7\n"
@ -95,13 +102,13 @@ BOOST_AUTO_TEST_CASE(multiline_comment)
char const* natspec = "{"
"\"methods\":{"
" \"mul_and_add\":{ \"user\": \" Multiplies `a` by 7\n and then adds `b`\"}"
" \"mul_and_add\":{ \"notice\": \" Multiplies `a` by 7\n and then adds `b`\"}"
"}}";
checkNatspec(sourceCode, natspec);
checkNatspec(sourceCode, natspec, true);
}
BOOST_AUTO_TEST_CASE(multiple_functions)
BOOST_AUTO_TEST_CASE(user_multiple_functions)
{
char const* sourceCode = "contract test {\n"
" /// Multiplies `a` by 7\n"
@ -125,22 +132,22 @@ BOOST_AUTO_TEST_CASE(multiple_functions)
char const* natspec = "{"
"\"methods\":{"
" \"mul_and_add\":{ \"user\": \" Multiplies `a` by 7\n and then adds `b`\"},"
" \"divide\":{ \"user\": \" Divides `input` by `div`\"},"
" \"sub\":{ \"user\": \" Subtracts 3 from `input`\"}"
" \"mul_and_add\":{ \"notice\": \" Multiplies `a` by 7\n and then adds `b`\"},"
" \"divide\":{ \"notice\": \" Divides `input` by `div`\"},"
" \"sub\":{ \"notice\": \" Subtracts 3 from `input`\"}"
"}}";
checkNatspec(sourceCode, natspec);
checkNatspec(sourceCode, natspec, true);
}
BOOST_AUTO_TEST_CASE(empty_contract)
BOOST_AUTO_TEST_CASE(user_empty_contract)
{
char const* sourceCode = "contract test {\n"
"}\n";
char const* natspec = "{\"methods\":{} }";
checkNatspec(sourceCode, natspec);
checkNatspec(sourceCode, natspec, true);
}

Loading…
Cancel
Save