From 149062c1380ecc18bd97d07ad67bc0b390f9e068 Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Thu, 26 Sep 2024 09:05:33 +0800 Subject: [PATCH] docs: disallow missing docs on crate level and allow where necessary (#222) --- src/cockroach_db/mod.rs | 4 ++++ src/consul/mod.rs | 2 ++ src/dynamodb_local/mod.rs | 2 ++ src/elastic_search/mod.rs | 2 ++ src/elasticmq/mod.rs | 2 ++ src/google_cloud_sdk_emulators/mod.rs | 16 ++++++++++++++++ src/k3s/mod.rs | 8 ++++++++ src/kafka/confluent.rs | 2 ++ src/lib.rs | 2 ++ src/minio/mod.rs | 10 ++++++++++ src/mongo/mod.rs | 17 ++++++++++------- src/mosquitto/mod.rs | 2 ++ src/mssql_server/mod.rs | 2 ++ src/nats/mod.rs | 6 ++++++ src/neo4j/mod.rs | 2 +- src/orientdb/mod.rs | 2 ++ src/parity_parity/mod.rs | 2 ++ 17 files changed, 75 insertions(+), 8 deletions(-) diff --git a/src/cockroach_db/mod.rs b/src/cockroach_db/mod.rs index e369b9c..58af24f 100644 --- a/src/cockroach_db/mod.rs +++ b/src/cockroach_db/mod.rs @@ -28,11 +28,15 @@ pub struct CockroachDb { } impl CockroachDb { + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously + #[allow(missing_docs)] pub fn new(cmd: CockroachDbCmd) -> Self { CockroachDb { cmd } } } +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously +#[allow(missing_docs)] #[derive(Debug, Clone, Copy)] pub enum CockroachDbCmd { StartSingleNode { insecure: bool }, diff --git a/src/consul/mod.rs b/src/consul/mod.rs index 95c1c39..6d7fd5b 100644 --- a/src/consul/mod.rs +++ b/src/consul/mod.rs @@ -28,6 +28,8 @@ pub struct Consul { } impl Consul { + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously + #[allow(missing_docs)] pub fn with_local_config(self, config: String) -> Self { let mut env_vars = self.env_vars; env_vars.insert(CONSUL_LOCAL_CONFIG.to_owned(), config); diff --git a/src/dynamodb_local/mod.rs b/src/dynamodb_local/mod.rs index ff059bc..f4c8a0c 100644 --- a/src/dynamodb_local/mod.rs +++ b/src/dynamodb_local/mod.rs @@ -4,6 +4,8 @@ const NAME: &str = "amazon/dynamodb-local"; const TAG: &str = "2.0.0"; const DEFAULT_WAIT: u64 = 3000; +#[allow(missing_docs)] +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously #[derive(Default, Debug, Clone)] pub struct DynamoDb { /// (remove if there is another variable) diff --git a/src/elastic_search/mod.rs b/src/elastic_search/mod.rs index 026c767..59a582a 100644 --- a/src/elastic_search/mod.rs +++ b/src/elastic_search/mod.rs @@ -21,6 +21,8 @@ pub const ELASTICSEARCH_API_PORT: ContainerPort = ContainerPort::Tcp(9200); /// [`Elasticsearch`]: https://elastic.co/ pub const ELASTICSEARCH_INTER_NODE_PORT: ContainerPort = ContainerPort::Tcp(9300); +#[allow(missing_docs)] +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously #[derive(Debug, Default, Clone)] pub struct ElasticSearch { /// (remove if there is another variable) diff --git a/src/elasticmq/mod.rs b/src/elasticmq/mod.rs index 1dcafab..e611c7b 100644 --- a/src/elasticmq/mod.rs +++ b/src/elasticmq/mod.rs @@ -3,6 +3,8 @@ use testcontainers::{core::WaitFor, Image}; const NAME: &str = "softwaremill/elasticmq"; const TAG: &str = "1.5.2"; +#[allow(missing_docs)] +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously #[derive(Debug, Default, Clone)] pub struct ElasticMq { /// (remove if there is another variable) diff --git a/src/google_cloud_sdk_emulators/mod.rs b/src/google_cloud_sdk_emulators/mod.rs index f856d83..328a8fc 100644 --- a/src/google_cloud_sdk_emulators/mod.rs +++ b/src/google_cloud_sdk_emulators/mod.rs @@ -35,6 +35,8 @@ pub const PUBSUB_PORT: u16 = 8085; /// [`Spanner`]: https://cloud.google.com/spanner pub const SPANNER_PORT: u16 = 9010; +#[allow(missing_docs)] +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously #[derive(Debug, Clone)] pub struct CloudSdkCmd { pub host: String, @@ -42,6 +44,8 @@ pub struct CloudSdkCmd { pub emulator: Emulator, } +#[allow(missing_docs)] +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously #[derive(Debug, Clone, Eq, PartialEq)] pub enum Emulator { Bigtable, @@ -81,6 +85,8 @@ impl IntoIterator for &CloudSdkCmd { } } +#[allow(missing_docs)] +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously #[derive(Debug, Clone)] pub struct CloudSdk { exposed_ports: Vec, @@ -124,6 +130,8 @@ impl CloudSdk { } } + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously + #[allow(missing_docs)] pub fn bigtable() -> Self { Self::new( BIGTABLE_PORT, @@ -132,6 +140,8 @@ impl CloudSdk { ) } + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously + #[allow(missing_docs)] pub fn firestore() -> Self { Self::new( FIRESTORE_PORT, @@ -140,6 +150,8 @@ impl CloudSdk { ) } + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously + #[allow(missing_docs)] pub fn datastore(project: impl Into) -> Self { let project = project.into(); Self::new( @@ -149,6 +161,8 @@ impl CloudSdk { ) } + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously + #[allow(missing_docs)] pub fn pubsub() -> Self { Self::new( PUBSUB_PORT, @@ -157,6 +171,8 @@ impl CloudSdk { ) } + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously + #[allow(missing_docs)] pub fn spanner() -> Self { Self::new( SPANNER_PORT, // gRPC port diff --git a/src/k3s/mod.rs b/src/k3s/mod.rs index 56a1392..3ce686c 100644 --- a/src/k3s/mod.rs +++ b/src/k3s/mod.rs @@ -70,12 +70,16 @@ pub struct K3s { cmd: K3sCmd, } +#[allow(missing_docs)] +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously #[derive(Debug, Clone)] pub struct K3sCmd { snapshotter: String, } impl K3sCmd { + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously + #[allow(missing_docs)] pub fn with_snapshotter(self, snapshotter: impl Into) -> Self { Self { snapshotter: snapshotter.into(), @@ -130,6 +134,8 @@ impl Image for K3s { } impl K3s { + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously + #[allow(missing_docs)] pub fn with_conf_mount(mut self, conf_mount_path: impl AsRef) -> Self { self.env_vars .insert(String::from("K3S_KUBECONFIG_MODE"), String::from("644")); @@ -142,6 +148,8 @@ impl K3s { } } + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously + #[allow(missing_docs)] pub fn read_kube_config(&self) -> io::Result { let k3s_conf_file_path = self .conf_mount diff --git a/src/kafka/confluent.rs b/src/kafka/confluent.rs index 558ca8c..9c11db3 100644 --- a/src/kafka/confluent.rs +++ b/src/kafka/confluent.rs @@ -18,6 +18,8 @@ pub const KAFKA_PORT: ContainerPort = ContainerPort::Tcp(9093); /// [`Zookeeper`]: https://zookeeper.apache.org/ pub const ZOOKEEPER_PORT: ContainerPort = ContainerPort::Tcp(2181); +#[allow(missing_docs)] +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously #[derive(Debug, Clone)] pub struct Kafka { env_vars: HashMap, diff --git a/src/lib.rs b/src/lib.rs index e1242ce..92e3a4d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,5 @@ +// let's document our code for other/future developers +#![deny(missing_docs)] #![cfg_attr(docsrs, deny(rustdoc::broken_intra_doc_links))] #![cfg_attr(docsrs, feature(doc_cfg))] #![doc( diff --git a/src/minio/mod.rs b/src/minio/mod.rs index f73474a..cd80fca 100644 --- a/src/minio/mod.rs +++ b/src/minio/mod.rs @@ -8,6 +8,8 @@ const TAG: &str = "RELEASE.2022-02-07T08-17-33Z"; const DIR: &str = "/data"; const CONSOLE_ADDRESS: &str = ":9001"; +#[allow(missing_docs)] +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously #[derive(Debug, Clone)] pub struct MinIO { env_vars: HashMap, @@ -29,10 +31,18 @@ impl Default for MinIO { } } +#[allow(missing_docs)] +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously #[derive(Debug, Clone)] pub struct MinIOServerCmd { + #[allow(missing_docs)] + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously pub dir: String, + #[allow(missing_docs)] + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously pub certs_dir: Option, + #[allow(missing_docs)] + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously pub json_log: bool, } diff --git a/src/mongo/mod.rs b/src/mongo/mod.rs index 9eb8a7e..b6c8da0 100644 --- a/src/mongo/mod.rs +++ b/src/mongo/mod.rs @@ -6,29 +6,32 @@ use testcontainers::{ const NAME: &str = "mongo"; const TAG: &str = "5.0.6"; -#[derive(Debug, Clone)] +#[allow(missing_docs)] +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously +#[derive(Default, Debug, Clone)] enum InstanceKind { + #[default] Standalone, ReplSet, } -impl Default for InstanceKind { - fn default() -> Self { - Self::Standalone - } -} - +#[allow(missing_docs)] +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously #[derive(Default, Debug, Clone)] pub struct Mongo { kind: InstanceKind, } impl Mongo { + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously + #[allow(missing_docs)] pub fn new() -> Self { Self { kind: InstanceKind::Standalone, } } + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously + #[allow(missing_docs)] pub fn repl_set() -> Self { Self { kind: InstanceKind::ReplSet, diff --git a/src/mosquitto/mod.rs b/src/mosquitto/mod.rs index 7806ab3..1a10a8a 100644 --- a/src/mosquitto/mod.rs +++ b/src/mosquitto/mod.rs @@ -26,6 +26,8 @@ use testcontainers::{core::WaitFor, Image}; const NAME: &str = "eclipse-mosquitto"; const TAG: &str = "2.0.18"; +#[allow(missing_docs)] +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously #[derive(Debug, Default, Clone)] pub struct Mosquitto { /// (remove if there is another variable) diff --git a/src/mssql_server/mod.rs b/src/mssql_server/mod.rs index 3824a24..bb02ae4 100644 --- a/src/mssql_server/mod.rs +++ b/src/mssql_server/mod.rs @@ -58,6 +58,8 @@ pub struct MssqlServer { impl MssqlServer { const NAME: &'static str = "mcr.microsoft.com/mssql/server"; const TAG: &'static str = "2022-CU14-ubuntu-22.04"; + /// Default Password for `MSSQL_SA_PASSWORD`. + /// If you want to set your own password, please use [`with_sa_password`] pub const DEFAULT_SA_PASSWORD: &'static str = "yourStrong(!)Password"; /// Sets the password as `MSSQL_SA_PASSWORD`. diff --git a/src/nats/mod.rs b/src/nats/mod.rs index 07998f2..108a7a4 100644 --- a/src/nats/mod.rs +++ b/src/nats/mod.rs @@ -13,6 +13,8 @@ pub struct Nats { cmd: NatsServerCmd, } +#[allow(missing_docs)] +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously #[derive(Default, Debug, Clone)] pub struct NatsServerCmd { user: Option, @@ -20,11 +22,15 @@ pub struct NatsServerCmd { } impl NatsServerCmd { + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously + #[allow(missing_docs)] pub fn with_user(mut self, user: &str) -> Self { self.user = Some(user.to_owned()); self } + // not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously + #[allow(missing_docs)] pub fn with_password(mut self, password: &str) -> Self { self.pass = Some(password.to_owned()); self diff --git a/src/neo4j/mod.rs b/src/neo4j/mod.rs index 8f96183..e017395 100644 --- a/src/neo4j/mod.rs +++ b/src/neo4j/mod.rs @@ -59,7 +59,7 @@ pub enum Neo4jLabsPlugin { /// You can also use it to validate your graph against constraints expressed in [SHACL](https://www.w3.org/TR/shacl/) or to run basic inferencing. /// Please see [their documentation](https://neo4j.com/labs/neosemantics/) for furhter details NeoSemantics, - // Allows specifying other plugins + /// Allows specifying other plugins Custom(String), } diff --git a/src/orientdb/mod.rs b/src/orientdb/mod.rs index 38f1962..2e9c229 100644 --- a/src/orientdb/mod.rs +++ b/src/orientdb/mod.rs @@ -5,6 +5,8 @@ use testcontainers::{core::WaitFor, Image}; const NAME: &str = "orientdb"; const TAG: &str = "3.2.19"; +#[allow(missing_docs)] +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously #[derive(Debug, Default, Clone)] pub struct OrientDb { /// (remove if there is another variable) diff --git a/src/parity_parity/mod.rs b/src/parity_parity/mod.rs index c87363d..28ebe9f 100644 --- a/src/parity_parity/mod.rs +++ b/src/parity_parity/mod.rs @@ -5,6 +5,8 @@ use testcontainers::{core::WaitFor, Image}; const NAME: &str = "parity/parity"; const TAG: &str = "v2.5.0"; +#[allow(missing_docs)] +// not having docs here is currently allowed to address the missing docs problem one place at a time. Helping us by documenting just one of these places helps other devs tremendously #[derive(Debug, Default, Clone)] pub struct ParityEthereum { /// (remove if there is another variable)