Store docstrings in AST annotations.

2 files changed, 211 insertions, 0 deletions

diff --git a/libsolidity/parsing/DocStringParser.cpp b/libsolidity/parsing/DocStringParser.cpp
new file mode 100644
index 00000000..bbee35f5
--- /dev/null
+++ b/libsolidity/parsing/DocStringParser.cpp
@@ -0,0 +1,141 @@
+
+#include <libsolidity/parsing/DocStringParser.h>
+#include <boost/range/irange.hpp>
+#include <libsolidity/interface/Utils.h>
+
+using namespace std;
+using namespace dev;
+using namespace dev::solidity;
+
+
+static inline string::const_iterator skipLineOrEOS(
+	string::const_iterator _nlPos,
+	string::const_iterator _end
+)
+{
+	return (_nlPos == _end) ? _end : ++_nlPos;
+}
+
+static inline string::const_iterator firstSpaceOrNl(
+	string::const_iterator _pos,
+	string::const_iterator _end
+)
+{
+	auto spacePos = find(_pos, _end, ' ');
+	auto nlPos = find(_pos, _end, '\n');
+	return (spacePos < nlPos) ? spacePos : nlPos;
+}
+
+bool DocStringParser::parse(string const& _docString, ErrorList& _errors)
+{
+	m_errors = &_errors;
+	m_errorsOccurred = false;
+	m_lastTag = nullptr;
+
+	auto currPos = _docString.begin();
+	auto end = _docString.end();
+
+	while (currPos != end)
+	{
+		auto tagPos = find(currPos, end, '@');
+		auto nlPos = find(currPos, end, '\n');
+
+		if (tagPos != end && tagPos < nlPos)
+		{
+			// we found a tag
+			auto tagNameEndPos = firstSpaceOrNl(tagPos, end);
+			if (tagNameEndPos == end)
+			{
+				appendError("End of tag " + string(tagPos, tagNameEndPos) + "not found");
+				break;
+			}
+
+			currPos = parseDocTag(tagNameEndPos + 1, end, string(tagPos + 1, tagNameEndPos));
+		}
+		else if (!!m_lastTag) // continuation of the previous tag
+			currPos = appendDocTag(currPos, end);
+		else if (currPos != end)
+		{
+			// if it begins without a tag then consider it as @notice
+			if (currPos == _docString.begin())
+			{
+				currPos = parseDocTag(currPos, end, "notice");
+				continue;
+			}
+			else if (nlPos == end) //end of text
+				break;
+			// else skip the line if a newline was found and we get here
+			currPos = nlPos + 1;
+		}
+	}
+	return !m_errorsOccurred;
+}
+
+DocStringParser::iter DocStringParser::parseDocTagLine(iter _pos, iter _end, bool _appending)
+{
+	solAssert(!!m_lastTag, "");
+	auto nlPos = find(_pos, _end, '\n');
+	if (_appending && _pos < _end && *_pos != ' ')
+		m_lastTag->content += " ";
+	copy(_pos, nlPos, back_inserter(m_lastTag->content));
+	return skipLineOrEOS(nlPos, _end);
+}
+
+DocStringParser::iter DocStringParser::parseDocTagParam(iter _pos, iter _end)
+{
+	// find param name
+	auto currPos = find(_pos, _end, ' ');
+	if (currPos == _end)
+	{
+		appendError("End of param name not found" + string(_pos, _end));
+		return _end;
+	}
+
+	auto paramName = string(_pos, currPos);
+
+	currPos += 1;
+	auto nlPos = find(currPos, _end, '\n');
+	auto paramDesc = string(currPos, nlPos);
+	newTag("param");
+	m_lastTag->paramName = paramName;
+	m_lastTag->content = paramDesc;
+
+	return skipLineOrEOS(nlPos, _end);
+}
+
+DocStringParser::iter DocStringParser::parseDocTag(iter _pos, iter _end, string const& _tag)
+{
+	// LTODO: need to check for @(start of a tag) between here and the end of line
+	// for all cases.
+	if (!m_lastTag || _tag != "")
+	{
+		if (_tag == "param")
+			return parseDocTagParam(_pos, _end);
+		else
+		{
+			newTag(_tag);
+			return parseDocTagLine(_pos, _end, false);
+		}
+	}
+	else
+		return appendDocTag(_pos, _end);
+}
+
+DocStringParser::iter DocStringParser::appendDocTag(iter _pos, iter _end)
+{
+	solAssert(!!m_lastTag, "");
+	return parseDocTagLine(_pos, _end, true);
+}
+
+void DocStringParser::newTag(string const& _tagName)
+{
+	m_lastTag = &m_docTags.insert(make_pair(_tagName, DocTag()))->second;
+}
+
+void DocStringParser::appendError(string const& _description)
+{
+	auto err = make_shared<Error>(Error::Type::DocstringParsingError);
+	*err << errinfo_comment(_description);
+	m_errors->push_back(err);
+	m_errorsOccurred = true;
+}
diff --git a/libsolidity/parsing/DocStringParser.h b/libsolidity/parsing/DocStringParser.h
new file mode 100644
index 00000000..f67b8bbd
--- /dev/null
+++ b/libsolidity/parsing/DocStringParser.h
@@ -0,0 +1,70 @@
+/*
+	This file is part of cpp-ethereum.
+
+	cpp-ethereum 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.
+
+	cpp-ethereum 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.
+
+	You should have received a copy of the GNU General Public License
+	along with cpp-ethereum.  If not, see <http://www.gnu.org/licenses/>.
+*/
+/**
+ * @author Lefteris <lefteris@ethdev.com>
+ * @date 2014, 2015
+ * Parses a given docstring into pieces introduced by tags.
+ */
+
+#pragma once
+
+#include <string>
+#include <libsolidity/interface/Exceptions.h>
+#include <libsolidity/ast/ASTAnnotations.h>
+
+namespace dev
+{
+namespace solidity
+{
+
+class DocStringParser
+{
+public:
+	/// Parse the given @a _docString and stores the parsed components internally.
+	/// @returns false on error and appends the error to @a _errors.
+	bool parse(std::string const& _docString, ErrorList& _errors);
+
+	std::multimap<std::string, DocTag> const& tags() const { return m_docTags; }
+
+private:
+	using iter = std::string::const_iterator;
+	void resetUser();
+	void resetDev();
+
+	iter parseDocTagLine(iter _pos, iter _end, bool _appending);
+	iter parseDocTagParam(iter _pos, iter _end);
+	iter appendDocTagParam(iter _pos, iter _end);
+	void parseDocString(std::string const& _string);
+	iter appendDocTag(iter _pos, iter _end);
+	/// Parses the doc tag named @a _tag, adds it to m_docTags and returns the position
+	/// after the tag.
+	iter parseDocTag(iter _pos, iter _end, std::string const& _tag);
+
+	/// Creates and inserts a new tag and adjusts m_lastTag.
+	void newTag(std::string const& _tagName);
+
+	void appendError(std::string const& _description);
+
+	/// Mapping tag name -> content.
+	std::multimap<std::string, DocTag> m_docTags;
+	DocTag* m_lastTag = nullptr;
+	ErrorList* m_errors = nullptr;
+	bool m_errorsOccurred = false;
+};
+
+} //solidity NS
+} // dev NS