Sentry API docs:

- Improve routing docs
Add query examples for:
- /v5/campaign/list
- /v5/channel/list
Improve other doc comments

Author: elpiel

primitives/Cargo.toml

@@ -16,6 +16,14 @@ postgres = ["bytes", "tokio-postgres", "deadpool-postgres"]
 # All Addresses and keystore files exist in the ganache-cli setup for testing with the EthereumAdapter
 test-util = []
 
+[[example]]
+name = "channel_list_query"
+required-features = ["test-util"]
+
+[[example]]
+name = "campaign_list_query"
+required-features = ["test-util"]
+
 [dependencies]
 # (De)Serialization
 serde = { version = "^1.0", features = ['derive'] }

sentry/examples/campaign_list_query.rs renamed to primitives/examples/campaign_list_query.rs

@@ -1,7 +1,7 @@
 use chrono::{TimeZone, Utc};
 use primitives::{
     sentry::campaign_list::{CampaignListQuery, ValidatorParam},
-    test_util::{ADVERTISER, FOLLOWER, LEADER},
+    test_util::{ADVERTISER, FOLLOWER, IDS, LEADER},
 };
 
 fn main() {
@@ -19,6 +19,9 @@ fn main() {
         assert!(query.validator.is_none());
     }
 
+    // In the following examples we always use `activeTo`
+    // as it makes simpler examples for assertions rather than using the default `Utc::now()`
+
     // Query with `activeTo` only
     {
         let active_to_query = "activeTo=1624192200";
@@ -64,13 +67,15 @@ fn main() {
     }
 
     // Query with `validator`
+    // You can either have `leader` or `validator` but not both!
     {
-        let with_creator_validator_query = "page=0&activeTo=1624192200&creator=0xDd589B43793934EF6Ad266067A0d1D4896b0dff0&validator=0xf3f583AEC5f7C030722Fe992A5688557e1B86ef7";
+        let with_creator_validator_query =
+            "activeTo=1624192200&validator=0xf3f583AEC5f7C030722Fe992A5688557e1B86ef7";
         let with_creator_validator = CampaignListQuery {
             page: 0,
             active_to_ge: Utc.ymd(2021, 6, 20).and_hms(12, 30, 0),
-            creator: Some(*ADVERTISER),
-            validator: Some(ValidatorParam::Validator((*FOLLOWER).into())),
+            creator: None,
+            validator: Some(ValidatorParam::Validator(IDS[&FOLLOWER])),
         };
 
         assert_eq!(
@@ -80,16 +85,31 @@ fn main() {
     }
 
     // Query with `leader`
+    // You can either have `leader` or `validator` but not both!
     {
-        let with_leader_query = "page=0&activeTo=1624192200&creator=0xDd589B43793934EF6Ad266067A0d1D4896b0dff0&leader=0x80690751969B234697e9059e04ed72195c3507fa";
+        let with_leader_query = "activeTo=1624192200&leader=0x80690751969B234697e9059e04ed72195c3507fa";
 
         let with_leader = CampaignListQuery {
             page: 0,
             active_to_ge: Utc.ymd(2021, 6, 20).and_hms(12, 30, 0),
-            creator: Some(*ADVERTISER),
-            validator: Some(ValidatorParam::Leader((*LEADER).into())),
+            creator: None,
+            validator: Some(ValidatorParam::Leader(IDS[&LEADER])),
         };
 
         assert_eq!(with_leader, serde_qs::from_str(with_leader_query).unwrap());
     }
+
+    // Query with all parameters and `validator`
+    // You can either have `leader` or `validator` but not both!
+    {
+        let full_query = "page=14&activeTo=1624192200&creator=0xDd589B43793934EF6Ad266067A0d1D4896b0dff0&validator=0xf3f583AEC5f7C030722Fe992A5688557e1B86ef7";
+        let full_expected = CampaignListQuery {
+            page: 14,
+            active_to_ge: Utc.ymd(2021, 6, 20).and_hms(12, 30, 0),
+            creator: Some(*ADVERTISER),
+            validator: Some(ValidatorParam::Validator(IDS[&FOLLOWER])),
+        };
+
+        assert_eq!(full_expected, serde_qs::from_str(full_query).unwrap());
+    }
 }

primitives/examples/channel_list_query.rs

@@ -0,0 +1,71 @@
+use primitives::{
+    sentry::channel_list::ChannelListQuery,
+    test_util::{IDS, LEADER},
+    ChainId,
+};
+
+fn main() {
+    // An empty query
+    {
+        let empty = "";
+        let empty_expected = ChannelListQuery {
+            page: 0,
+            validator: None,
+            chains: vec![],
+        };
+
+        assert_eq!(empty_expected, serde_qs::from_str(empty).unwrap());
+    }
+
+    // Query with `page`
+    {
+        let only_page = "page=14";
+        let only_page_expected = ChannelListQuery {
+            page: 14,
+            validator: None,
+            chains: vec![],
+        };
+
+        assert_eq!(only_page_expected, serde_qs::from_str(only_page).unwrap());
+    }
+
+    // Query with `validator`
+    {
+        let only_validator = "validator=0x80690751969B234697e9059e04ed72195c3507fa";
+        let only_validator_expected = ChannelListQuery {
+            page: 0,
+            validator: Some(IDS[&LEADER]),
+            chains: vec![],
+        };
+
+        assert_eq!(
+            only_validator_expected,
+            serde_qs::from_str(only_validator).unwrap()
+        );
+    }
+
+    // Query with `chains`
+    {
+        let chains_query = "chains[]=1&chains[]=1337";
+        let chains_expected = ChannelListQuery {
+            page: 0,
+            validator: None,
+            chains: vec![ChainId::new(1), ChainId::new(1337)],
+        };
+
+        assert_eq!(chains_expected, serde_qs::from_str(chains_query).unwrap());
+    }
+
+    // Query with all parameters
+    {
+        let all_query =
+            "page=14&validator=0x80690751969B234697e9059e04ed72195c3507fa&chains[]=1&chains[]=1337";
+        let all_expected = ChannelListQuery {
+            page: 14,
+            validator: Some(IDS[&LEADER]),
+            chains: vec![ChainId::new(1), ChainId::new(1337)],
+        };
+
+        assert_eq!(all_expected, serde_qs::from_str(all_query).unwrap());
+    }
+}

primitives/src/address.rs

@@ -111,12 +111,13 @@ impl TryFrom<&str> for Address {
     }
 }
 
-/// When we have a string literal (&str) representation of the Address in the form of bytes.
+/// When we have a string literal (`&str`) representation of the `Address` in the form of bytes.
 /// Useful for creating static values from strings for testing, configuration, etc.
 ///
-/// You can find a test setup example in the [`crate::test_util`] module.
+/// You can find a test setup example in the `crate::test_util` module (requires `test-util` feature).
 ///
 /// # Example
+///
 /// ```
 /// use once_cell::sync::Lazy;
 /// use primitives::Address;

primitives/src/sentry.rs

@@ -653,7 +653,14 @@ pub mod channel_list {
         pub pagination: Pagination,
     }
 
-    #[derive(Debug, Serialize, Deserialize)]
+    /// `GET /v5/channel/list` query
+    ///
+    /// # Examples
+    ///
+    /// ```
+    #[doc = include_str!("../examples/channel_list_query.rs")]
+    /// ```
+    #[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
     pub struct ChannelListQuery {
         /// default is `u64::default()` = `0`
         #[serde(default)]
@@ -681,6 +688,13 @@ pub mod campaign_list {
         pub pagination: Pagination,
     }
 
+    /// `GET /v5/campaign/list` query
+    ///
+    /// # Examples
+    ///
+    /// ```
+    #[doc = include_str!("../examples/campaign_list_query.rs")]
+    /// ```
     #[derive(Debug, Serialize, Deserialize, PartialEq)]
     pub struct CampaignListQuery {
         /// default is `u64::default()` = `0`