aboutsummaryrefslogtreecommitdiffstats
path: root/libsolidity/interface/Natspec.cpp
blob: 7f7084ef3a9f7c8a92431bbf1d07194f109dc387 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
/*
        This file is part of solidity.

        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.

        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.

        You should have received a copy of the GNU General Public License
        along with solidity.  If not, see <http://www.gnu.org/licenses/>.
*/
/**
 * @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
 */

#include <libsolidity/interface/Natspec.h>
#include <boost/range/irange.hpp>
#include <libsolidity/ast/AST.h>

using namespace std;
using namespace dev;
using namespace dev::solidity;

Json::Value Natspec::userDocumentation(ContractDefinition const& _contractDef)
{
    Json::Value doc;
    Json::Value methods(Json::objectValue);

    for (auto const& it: _contractDef.interfaceFunctions())
        if (it.second->hasDeclaration())
            if (auto const* f = dynamic_cast<FunctionDefinition const*>(&it.second->declaration()))
            {
                string value = extractDoc(f->annotation().docTags, "notice");
                if (!value.empty())
                {
                    Json::Value user;
                    // since @notice is the only user tag if missing function should not appear
                    user["notice"] = Json::Value(value);
                    methods[it.second->externalSignature()] = user;
                }
            }
    doc["methods"] = methods;

    return doc;
}

Json::Value Natspec::devDocumentation(ContractDefinition const& _contractDef)
{
    Json::Value doc;
    Json::Value methods(Json::objectValue);

    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;

    for (auto const& it: _contractDef.interfaceFunctions())
    {
        if (!it.second->hasDeclaration())
            continue;
        Json::Value method;
        if (auto fun = dynamic_cast<FunctionDefinition const*>(&it.second->declaration()))
        {
            auto dev = extractDoc(fun->annotation().docTags, "dev");
            if (!dev.empty())
                method["details"] = Json::Value(dev);

            auto author = extractDoc(fun->annotation().docTags, "author");
            if (!author.empty())
                method["author"] = author;

            auto ret = extractDoc(fun->annotation().docTags, "return");
            if (!ret.empty())
                method["return"] = ret;

            Json::Value params(Json::objectValue);
            auto paramRange = fun->annotation().docTags.equal_range("param");
            for (auto i = paramRange.first; i != paramRange.second; ++i)
                params[i->second.paramName] = Json::Value(i->second.content);

            if (!params.empty())
                method["params"] = params;

            if (!method.empty())
                // add the function, only if we have any documentation to add
                methods[it.second->externalSignature()] = method;
        }
    }
    doc["methods"] = methods;

    return doc;
}

string Natspec::extractDoc(multimap<string, DocTag> const& _tags, string const& _name)
{
    string value;
    auto range = _tags.equal_range(_name);
    for (auto i = range.first; i != range.second; i++)
        value += i->second.content;
    return value;
}