Adds JSON import / export for structured documentation.

libsolidity/ast/ASTJsonConverter.cpp

@@ -268,7 +268,7 @@ bool ASTJsonConverter::visit(ContractDefinition const& _node)
 {
 	setJsonNode(_node, "ContractDefinition", {
 		make_pair("name", _node.name()),
-		make_pair("documentation", _node.documentation() ? Json::Value(*_node.documentation()) : Json::nullValue),
+		make_pair("documentation", _node.documentation() ? toJson(*_node.documentation()) : Json::nullValue),
 		make_pair("contractKind", contractKind(_node.contractKind())),
 		make_pair("abstract", _node.abstract()),
 		make_pair("fullyImplemented", _node.annotation().unimplementedFunctions.empty()),
@@ -349,7 +349,7 @@ bool ASTJsonConverter::visit(FunctionDefinition const& _node)
 {
 	std::vector<pair<string, Json::Value>> attributes = {
 		make_pair("name", _node.name()),
-		make_pair("documentation", _node.documentation() ? Json::Value(*_node.documentation()) : Json::nullValue),
+		make_pair("documentation", _node.documentation() ? toJson(*_node.documentation()) : Json::nullValue),
 		make_pair("kind", TokenTraits::toString(_node.kind())),
 		make_pair("stateMutability", stateMutabilityToString(_node.stateMutability())),
 		make_pair("visibility", Declaration::visibilityToString(_node.visibility())),
@@ -400,7 +400,7 @@ bool ASTJsonConverter::visit(ModifierDefinition const& _node)
 {
 	std::vector<pair<string, Json::Value>> attributes = {
 		make_pair("name", _node.name()),
-		make_pair("documentation", _node.documentation() ? Json::Value(*_node.documentation()) : Json::nullValue),
+		make_pair("documentation", _node.documentation() ? toJson(*_node.documentation()) : Json::nullValue),
 		make_pair("visibility", Declaration::visibilityToString(_node.visibility())),
 		make_pair("parameters", toJson(_node.parameterList())),
 		make_pair("virtual", _node.markedVirtual()),
@@ -427,7 +427,7 @@ bool ASTJsonConverter::visit(EventDefinition const& _node)
 	m_inEvent = true;
 	setJsonNode(_node, "EventDefinition", {
 		make_pair("name", _node.name()),
-		make_pair("documentation", _node.documentation() ? Json::Value(*_node.documentation()) : Json::nullValue),
+		make_pair("documentation", _node.documentation() ? toJson(*_node.documentation()) : Json::nullValue),
 		make_pair("parameters", toJson(_node.parameterList())),
 		make_pair("anonymous", _node.isAnonymous())
 	});
@@ -833,6 +833,17 @@ bool ASTJsonConverter::visit(Literal const& _node)
 	return false;
 }
 
+bool ASTJsonConverter::visit(StructuredDocumentation const& _node)
+{
+	Json::Value text{*_node.text()};
+	std::vector<pair<string, Json::Value>> attributes = {
+		make_pair("text", text)
+	};
+	setJsonNode(_node, "StructuredDocumentation", std::move(attributes));
+	return false;
+}
+
+
 
 void ASTJsonConverter::endVisit(EventDefinition const&)
 {

libsolidity/ast/ASTJsonConverter.h

@@ -119,6 +119,7 @@ public:
 	bool visit(Identifier const& _node) override;
 	bool visit(ElementaryTypeNameExpression const& _node) override;
 	bool visit(Literal const& _node) override;
+	bool visit(StructuredDocumentation const& _node) override;
 
 	void endVisit(EventDefinition const&) override;
 

libsolidity/ast/ASTJsonImporter.cpp

@@ -208,6 +208,8 @@ ASTPointer<ASTNode> ASTJsonImporter::convertJsonToASTNode(Json::Value const& _js
 		return createElementaryTypeNameExpression(_json);
 	if (nodeType == "Literal")
 		return createLiteral(_json);
+	if (nodeType == "StructuredDocumentation")
+		return createDocumentation(_json);
 	else
 		astAssert(false, "Unknown type of ASTNode: " + nodeType);
 }
@@ -283,7 +285,7 @@ ASTPointer<ContractDefinition> ASTJsonImporter::createContractDefinition(Json::V
 	return createASTNode<ContractDefinition>(
 		_node,
 		make_shared<ASTString>(_node["name"].asString()),
-		nullOrASTString(_node, "documentation"),
+		_node["documentation"].isNull() ? nullptr : createDocumentation(member(_node, "documentation")),
 		baseContracts,
 		subNodes,
 		contractKind(_node),
@@ -397,7 +399,7 @@ ASTPointer<FunctionDefinition> ASTJsonImporter::createFunctionDefinition(Json::V
 		kind,
 		memberAsBool(_node, "virtual"),
 		_node["overrides"].isNull() ? nullptr : createOverrideSpecifier(member(_node, "overrides")),
-		nullOrASTString(_node, "documentation"),
+		_node["documentation"].isNull() ? nullptr : createDocumentation(member(_node, "documentation")),
 		createParameterList(member(_node, "parameters")),
 		modifiers,
 		createParameterList(member(_node, "returnParameters")),
@@ -428,7 +430,7 @@ ASTPointer<ModifierDefinition> ASTJsonImporter::createModifierDefinition(Json::V
 	return createASTNode<ModifierDefinition>(
 		_node,
 		memberAsASTString(_node, "name"),
-		nullOrASTString(_node,"documentation"),
+		_node["documentation"].isNull() ? nullptr : createDocumentation(member(_node, "documentation")),
 		createParameterList(member(_node, "parameters")),
 		memberAsBool(_node, "virtual"),
 		_node["overrides"].isNull() ? nullptr : createOverrideSpecifier(member(_node, "overrides")),
@@ -453,7 +455,7 @@ ASTPointer<EventDefinition> ASTJsonImporter::createEventDefinition(Json::Value c
 	return createASTNode<EventDefinition>(
 		_node,
 		memberAsASTString(_node, "name"),
-		nullOrASTString(_node, "documentation"),
+		_node["documentation"].isNull() ? nullptr : createDocumentation(member(_node, "documentation")),
 		createParameterList(member(_node, "parameters")),
 		memberAsBool(_node, "anonymous")
 	);
@@ -842,6 +844,18 @@ ASTPointer<ASTNode> ASTJsonImporter::createLiteral(Json::Value const&  _node)
 	);
 }
 
+ASTPointer<StructuredDocumentation> ASTJsonImporter::createDocumentation(Json::Value const&  _node)
+{
+	static string const textString = "text";
+
+	astAssert(member(_node, textString).isString(), "'text' must be a string");
+
+	return createASTNode<StructuredDocumentation>(
+		_node,
+		make_shared<ASTString>(_node[textString].asString())
+	);
+}
+
 // ===== helper functions ==========
 
 Json::Value ASTJsonImporter::member(Json::Value const& _node, string const& _name)

libsolidity/ast/ASTJsonImporter.h

@@ -119,6 +119,7 @@ private:
 	ASTPointer<Identifier> createIdentifier(Json::Value const& _node);
 	ASTPointer<ElementaryTypeNameExpression> createElementaryTypeNameExpression(Json::Value const& _node);
 	ASTPointer<ASTNode> createLiteral(Json::Value const& _node);
+	ASTPointer<StructuredDocumentation> createDocumentation(Json::Value const& _node);
 	///@}
 
 	// =============== general helper functions ===================

test/libsolidity/ASTJSON/documentation.json

@@ -4,10 +4,10 @@
   {
     "C":
     [
-      1
+      2
     ]
   },
-  "id": 2,
+  "id": 3,
   "nodeType": "SourceUnit",
   "nodes":
   [
@@ -16,17 +16,23 @@
       "baseContracts": [],
       "contractDependencies": [],
       "contractKind": "contract",
-      "documentation": "This contract is empty",
+      "documentation":
-      "fullyImplemented": true,
+      {
         "id": 1,
+        "nodeType": "StructuredDocumentation",
+        "src": "0:27:1",
+        "text": "This contract is empty"
+      },
+      "fullyImplemented": true,
+      "id": 2,
       "linearizedBaseContracts":
       [
-        1
+        2
       ],
       "name": "C",
       "nodeType": "ContractDefinition",
       "nodes": [],
-      "scope": 2,
+      "scope": 3,
       "src": "28:13:1"
     }
   ],
@@ -38,10 +44,10 @@
   {
     "C":
     [
-      3
+      5
     ]
   },
-  "id": 4,
+  "id": 6,
   "nodeType": "SourceUnit",
   "nodes":
   [
@@ -50,17 +56,23 @@
       "baseContracts": [],
       "contractDependencies": [],
       "contractKind": "contract",
-      "documentation": "This contract is empty\nand has a line-breaking comment.",
+      "documentation":
+      {
+        "id": 4,
+        "nodeType": "StructuredDocumentation",
+        "src": "0:61:2",
+        "text": "This contract is empty\nand has a line-breaking comment."
+      },
       "fullyImplemented": true,
-      "id": 3,
+      "id": 5,
       "linearizedBaseContracts":
       [
-        3
+        5
       ],
       "name": "C",
       "nodeType": "ContractDefinition",
       "nodes": [],
-      "scope": 4,
+      "scope": 6,
       "src": "62:13:2"
     }
   ],
@@ -72,10 +84,10 @@
   {
     "C":
     [
-      15
+      20
     ]
   },
-  "id": 16,
+  "id": 21,
   "nodeType": "SourceUnit",
   "nodes":
   [
@@ -86,10 +98,10 @@
       "contractKind": "contract",
       "documentation": null,
       "fullyImplemented": true,
-      "id": 15,
+      "id": 20,
       "linearizedBaseContracts":
       [
-        15
+        20
       ],
       "name": "C",
       "nodeType": "ContractDefinition",
@@ -97,13 +109,19 @@
       [
         {
           "anonymous": false,
-          "documentation": "Some comment on Evt.",
+          "documentation":
-          "id": 6,
+          {
+            "id": 7,
+            "nodeType": "StructuredDocumentation",
+            "src": "15:26:3",
+            "text": "Some comment on Evt."
+          },
+          "id": 9,
           "name": "Evt",
           "nodeType": "EventDefinition",
           "parameters":
           {
-            "id": 5,
+            "id": 8,
             "nodeType": "ParameterList",
             "parameters": [],
             "src": "51:2:3"
@@ -113,26 +131,32 @@
         {
           "body":
           {
-            "id": 9,
+            "id": 13,
             "nodeType": "Block",
             "src": "99:6:3",
             "statements":
             [
               {
-                "id": 8,
+                "id": 12,
                 "nodeType": "PlaceholderStatement",
                 "src": "101:1:3"
               }
             ]
           },
-          "documentation": "Some comment on mod.",
+          "documentation":
+          {
             "id": 10,
+            "nodeType": "StructuredDocumentation",
+            "src": "57:26:3",
+            "text": "Some comment on mod."
+          },
+          "id": 14,
           "name": "mod",
           "nodeType": "ModifierDefinition",
           "overrides": null,
           "parameters":
           {
-            "id": 7,
+            "id": 11,
             "nodeType": "ParameterList",
             "parameters": [],
             "src": "96:2:3"
@@ -144,14 +168,20 @@
         {
           "body":
           {
-            "id": 13,
+            "id": 18,
             "nodeType": "Block",
             "src": "155:2:3",
             "statements": []
           },
-          "documentation": "Some comment on fn.",
+          "documentation":
+          {
+            "id": 15,
+            "nodeType": "StructuredDocumentation",
+            "src": "108:25:3",
+            "text": "Some comment on fn."
+          },
           "functionSelector": "a4a2c40b",
-          "id": 14,
+          "id": 19,
           "implemented": true,
           "kind": "function",
           "modifiers": [],
@@ -160,26 +190,26 @@
           "overrides": null,
           "parameters":
           {
-            "id": 11,
+            "id": 16,
             "nodeType": "ParameterList",
             "parameters": [],
             "src": "145:2:3"
           },
           "returnParameters":
           {
-            "id": 12,
+            "id": 17,
             "nodeType": "ParameterList",
             "parameters": [],
             "src": "155:0:3"
           },
-          "scope": 15,
+          "scope": 20,
           "src": "134:23:3",
           "stateMutability": "nonpayable",
           "virtual": false,
           "visibility": "public"
         }
       ],
-      "scope": 16,
+      "scope": 21,
       "src": "0:159:3"
     }
   ],

test/libsolidity/ASTJSON/documentation_legacy.json

@@ -6,7 +6,7 @@
     {
       "C":
       [
-        15
+        20
       ]
     }
   },
@@ -29,10 +29,10 @@
         "fullyImplemented": true,
         "linearizedBaseContracts":
         [
-          15
+          20
         ],
         "name": "C",
-        "scope": 16
+        "scope": 21
       },
       "children":
       [
@@ -40,11 +40,19 @@
           "attributes":
           {
             "anonymous": false,
-            "documentation": "Some comment on Evt.",
             "name": "Evt"
           },
           "children":
           [
+            {
+              "attributes":
+              {
+                "text": "Some comment on Evt."
+              },
+              "id": 7,
+              "name": "StructuredDocumentation",
+              "src": "15:26:3"
+            },
             {
               "attributes":
               {
@@ -54,19 +62,18 @@
                 ]
               },
               "children": [],
-              "id": 5,
+              "id": 8,
               "name": "ParameterList",
               "src": "51:2:3"
             }
           ],
-          "id": 6,
+          "id": 9,
           "name": "EventDefinition",
           "src": "42:12:3"
         },
         {
           "attributes":
           {
-            "documentation": "Some comment on mod.",
             "name": "mod",
             "overrides": null,
             "virtual": false,
@@ -77,55 +84,12 @@
             {
               "attributes":
               {
-                "parameters":
+                "text": "Some comment on mod."
-                [
-                  null
-                ]
               },
-              "children": [],
-              "id": 7,
-              "name": "ParameterList",
-              "src": "96:2:3"
-            },
-            {
-              "children":
-              [
-                {
-                  "id": 8,
-                  "name": "PlaceholderStatement",
-                  "src": "101:1:3"
-                }
-              ],
-              "id": 9,
-              "name": "Block",
-              "src": "99:6:3"
-            }
-          ],
               "id": 10,
-          "name": "ModifierDefinition",
+              "name": "StructuredDocumentation",
-          "src": "84:21:3"
+              "src": "57:26:3"
             },
-        {
-          "attributes":
-          {
-            "documentation": "Some comment on fn.",
-            "functionSelector": "a4a2c40b",
-            "implemented": true,
-            "isConstructor": false,
-            "kind": "function",
-            "modifiers":
-            [
-              null
-            ],
-            "name": "fn",
-            "overrides": null,
-            "scope": 15,
-            "stateMutability": "nonpayable",
-            "virtual": false,
-            "visibility": "public"
-          },
-          "children":
-          [
             {
               "attributes":
               {
@@ -137,6 +101,66 @@
               "children": [],
               "id": 11,
               "name": "ParameterList",
+              "src": "96:2:3"
+            },
+            {
+              "children":
+              [
+                {
+                  "id": 12,
+                  "name": "PlaceholderStatement",
+                  "src": "101:1:3"
+                }
+              ],
+              "id": 13,
+              "name": "Block",
+              "src": "99:6:3"
+            }
+          ],
+          "id": 14,
+          "name": "ModifierDefinition",
+          "src": "84:21:3"
+        },
+        {
+          "attributes":
+          {
+            "functionSelector": "a4a2c40b",
+            "implemented": true,
+            "isConstructor": false,
+            "kind": "function",
+            "modifiers":
+            [
+              null
+            ],
+            "name": "fn",
+            "overrides": null,
+            "scope": 20,
+            "stateMutability": "nonpayable",
+            "virtual": false,
+            "visibility": "public"
+          },
+          "children":
+          [
+            {
+              "attributes":
+              {
+                "text": "Some comment on fn."
+              },
+              "id": 15,
+              "name": "StructuredDocumentation",
+              "src": "108:25:3"
+            },
+            {
+              "attributes":
+              {
+                "parameters":
+                [
+                  null
+                ]
+              },
+              "children": [],
+              "id": 16,
+              "name": "ParameterList",
               "src": "145:2:3"
             },
             {
@@ -148,7 +172,7 @@
                 ]
               },
               "children": [],
-              "id": 12,
+              "id": 17,
               "name": "ParameterList",
               "src": "155:0:3"
             },
@@ -161,22 +185,22 @@
                 ]
               },
               "children": [],
-              "id": 13,
+              "id": 18,
               "name": "Block",
               "src": "155:2:3"
             }
           ],
-          "id": 14,
+          "id": 19,
           "name": "FunctionDefinition",
           "src": "134:23:3"
         }
       ],
-      "id": 15,
+      "id": 20,
       "name": "ContractDefinition",
       "src": "0:159:3"
     }
   ],
-  "id": 16,
+  "id": 21,
   "name": "SourceUnit",
   "src": "0:160:3"
 }