Followup test for checking propagated documentation (#514)

* codegen: Composite fields docs Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * codegen: Propagate docs for Event type Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * codegen: Propagate docs for calls module Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * subxt: Update polkadot.rs Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * codegen: Propagate documentation for `TypeDefGenKind::Enum` kind Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * subxt: Update polkadot.rs Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * codegen/tests: Recursively obtain raw metadata documentation Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * codegen/tests: Generate runtime interface from node metadata Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * codegen/tests: Obtain documentation from generated runtime API Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * codegen/tests: Match raw documentation with the generated one Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Revert not longer needed "codegen: Composite fields docs" This reverts commit 5460bbafc6262ac4f53e11d4ef11e44e1ce8296f. * codegen/tests: Improve test regex documentation Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * subxt: Add integration-tests feature flag Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * subxt: Guard integration tests under feature flag Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * test-runtime: Place build.rs under feature flag Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * subxt: Pass `integration-tests` feature to `test-runtime` Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * CI: Use `integration-tests` feature to run all tests Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * subxt: Rely on `#[cfg(feature = "integration-tests")]` for integration Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * subxt/metadata: Manually construct test metadata Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * artifacts: Move scale binary blob to dedicated folder Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * examples: Update path to metadata blob Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * metadata: Rely on artifact metadata blob for benches Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * metadata: Remove `test-runtime` dependency Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * examples: Modify runtime path for `custom_type_derives` Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * subxt: Remove tests folder Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * test-runtime: Remove `integration-tests` feature flag Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * integration-tests: Add an integration test crate for subxt Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * subxt: Remove `test-runtime` dependency Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * subxt: Add comment for feature flags Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * integration-tests: Trim dependencies Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * integration-tests: Move dependencies under dev Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Revert "CI: Use `integration-tests` feature to run all tests" This reverts commit 8e5f38ba8c633ac40420fadf58700ac402f762d4. * codegen: Move documentation test to integration crate Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * codegen_documentation: Add license + fmt Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Update `polkadot.rs` Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Move test under `testing` folder Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io> * Update testing/integration-tests/src/codegen/codegen_documentation.rs Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com> Co-authored-by: Tarik Gul <47201679+TarikGul@users.noreply.github.com>
2026-04-23 18:57:59 +00:00 · 2022-06-17 20:25:13 +03:00
parent cb18ad75f3
commit 0d67b80cc5
10 changed files with 565 additions and 688 deletions
@@ -0,0 +1,119 @@
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
+// This file is part of subxt.
+//
+// subxt 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.
+//
+// subxt 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 subxt.  If not, see <http://www.gnu.org/licenses/>.
+
+use regex::Regex;
+use subxt_codegen::{
+    DerivesRegistry,
+    RuntimeGenerator,
+};
+
+fn metadata_docs() -> Vec<String> {
+    // Load the runtime metadata downloaded from a node via `test-runtime`.
+    let bytes = test_runtime::METADATA;
+    let meta: frame_metadata::RuntimeMetadataPrefixed =
+        codec::Decode::decode(&mut &*bytes).expect("Cannot decode scale metadata");
+    let metadata = match meta.1 {
+        frame_metadata::RuntimeMetadata::V14(v14) => v14,
+        _ => panic!("Unsupported metadata version {:?}", meta.1),
+    };
+
+    // Inspect the metadata types and collect the documentation.
+    let mut docs = Vec::new();
+    for ty in metadata.types.types() {
+        docs.extend_from_slice(ty.ty().docs());
+    }
+
+    for pallet in metadata.pallets {
+        if let Some(storage) = pallet.storage {
+            for entry in storage.entries {
+                docs.extend(entry.docs);
+            }
+        }
+        // Note: Calls, Events and Errors are deduced directly to
+        // PortableTypes which are handled above.
+        for constant in pallet.constants {
+            docs.extend(constant.docs);
+        }
+    }
+    // Note: Extrinsics do not have associated documentation, but is implied by
+    // associated Type.
+
+    docs
+}
+
+fn generate_runtime_interface() -> String {
+    // Load the runtime metadata downloaded from a node via `test-runtime`.
+    let bytes = test_runtime::METADATA;
+    let metadata: frame_metadata::RuntimeMetadataPrefixed =
+        codec::Decode::decode(&mut &*bytes).expect("Cannot decode scale metadata");
+
+    // Generate a runtime interface from the provided metadata.
+    let generator = RuntimeGenerator::new(metadata);
+    let item_mod = syn::parse_quote!(
+        pub mod api {}
+    );
+    let derives = DerivesRegistry::default();
+    generator.generate_runtime(item_mod, derives).to_string()
+}
+
+fn interface_docs() -> Vec<String> {
+    // Generate the runtime interface from the node's metadata.
+    // Note: the API is generated on a single line.
+    let runtime_api = generate_runtime_interface();
+
+    // Documentation lines have the following format:
+    //    # [ doc = "Upward message is invalid XCM."]
+    // Given the API is generated on a single line, the regex matching
+    // must be lazy hence the `?` in the matched group `(.*?)`.
+    //
+    // The greedy `non-?` matching would lead to one single match
+    // from the beginning of the first documentation tag, containing everything up to
+    // the last documentation tag
+    // `# [ doc = "msg"] # [ doc = "msg2"] ... api ... # [ doc = "msgN" ]`
+    //
+    // The `(.*?)` stands for match any character zero or more times lazily.
+    let re = Regex::new(r#"\# \[doc = "(.*?)"\]"#).unwrap();
+    re.captures_iter(&runtime_api)
+        .filter_map(|capture| {
+            // Get the matched group (ie index 1).
+            capture.get(1).as_ref().map(|doc| {
+                // Generated documentation will escape special characters.
+                // Replace escaped characters with unescaped variants for
+                // exact matching on the raw metadata documentation.
+                doc.as_str()
+                    .replace("\\n", "\n")
+                    .replace("\\t", "\t")
+                    .replace("\\\"", "\"")
+            })
+        })
+        .collect()
+}
+
+#[test]
+fn check_documentation() {
+    // Inspect metadata recursively and obtain all associated documentation.
+    let raw_docs = metadata_docs();
+    // Obtain documentation from the generated API.
+    let runtime_docs = interface_docs();
+
+    for raw in raw_docs.iter() {
+        assert!(
+            runtime_docs.contains(raw),
+            "Documentation not present in runtime API: {}",
+            raw
+        );
+    }
+}