Remove #[doc(hidden)] from stable crates (#3226)

This PR removes `#[doc(hidden)]` from types/functions in stable crates (as defined in [CrateSet.kt](https://github.com/smithy-lang/smithy-rs/blob/ad520b080aa0a3e8239ab2857dafb519c3458088/buildSrc/src/main/kotlin/CrateSet.kt#L19-L33)). They are now `pub`, however, for those that are not intended to be used directly, we preserve the original docs to be explicit about it. After this PR, stable crates contain neither <details> <summary>#[doc(hidden)]</summary> ``` ➜ smithy-rs git:(ysaito/remove-doc-hidden) rg -l '#\[doc\(hidden\)\]' aws/rust-runtime/aws-http/src/user_agent.rs CHANGELOG.next.toml CHANGELOG.md rust-runtime/aws-smithy-http/src/lib.rs rust-runtime/aws-smithy-http/src/event_stream/sender.rs rust-runtime/aws-smithy-http/src/event_stream/receiver.rs codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/error/ErrorImplGenerator.kt (this is only for CodegenTarget.SERVER) codegen-core/src/test/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/StructureGeneratorTest.kt design/src/server/instrumentation.md design/src/rfcs/rfc0039_forward_compatible_errors.md design/src/rfcs/rfc0032_better_constraint_violations.md design/src/rfcs/rfc0026_client_crate_organization.md rust-runtime/aws-smithy-http-server/src/macros.rs rust-runtime/aws-smithy-http-server/src/routing/mod.rs rust-runtime/aws-smithy-http-server/src/shape_id.rs rust-runtime/aws-smithy-http-server/src/body.rs rust-runtime/aws-smithy-http-server/src/lib.rs rust-runtime/aws-smithy-http-server/src/plugin/mod.rs codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/MapConstraintViolationGenerator.kt codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/CollectionConstraintViolationGenerator.kt ``` </details> nor <details> <summary>DocHidden</summary> ``` ➜ smithy-rs git:(ysaito/remove-doc-hidden) rg -l 'DocHidden' codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/rustlang/RustType.kt codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ServerBuilderConstraintViolations.kt ``` </details>  - [x] I have updated `CHANGELOG.next.toml` if I made changes to the smithy-rs codegen or runtime crates - [x] I have updated `CHANGELOG.next.toml` if I made changes to the AWS SDK, generated SDK code, or SDK runtime crates ---- _By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice._ --------- Co-authored-by: Russell Cohen <[email protected]>
smithy-lang · Nov 17, 2023 · cf17841 · cf17841
1 parent c862fb8
commit cf17841
Show file tree

Hide file tree

Showing 29 changed files with 264 additions and 231 deletions.
diff --git a/CHANGELOG.next.toml b/CHANGELOG.next.toml
@@ -104,3 +104,15 @@ message = "Add `Display` impl for `DateTime`."
 references = ["smithy-rs#3183"]
 meta = { "breaking" = false, "tada" = true, "bug" = false, "target" = "all" }
 author = "HakanVardarr"
+
+[[smithy-rs]]
+message = "Types/functions that were previously `#[doc(hidden)]` in `aws-smithy-async`, `aws-smithy-runtime-api`, `aws-smithy-runtime`, `aws-smithy-types`, and the SDK crates are now visible. For those that are not intended to be used directly, they are called out in their docs as such."
+references = ["smithy-rs#3226"]
+meta = { "breaking" = false, "tada" = false, "bug" = false, "target" = "client" }
+author = "ysaito1001"
+
+[[aws-sdk-rust]]
+message = "Types/functions that were previously `#[doc(hidden)]` in `aws-config`, `aws-inlineable`, `aws-types`, and the SDK crates are now visible. For those that are not intended to be used directly, they are called out in their docs as such."
+references = ["smithy-rs#3226"]
+meta = { "breaking" = false, "tada" = false, "bug" = false }
+author = "ysaito1001"
diff --git a/aws/rust-runtime/aws-config/src/default_provider/app_name.rs b/aws/rust-runtime/aws-config/src/default_provider/app_name.rs
@@ -41,11 +41,10 @@ pub struct Builder {
 }
 
 impl Builder {
-    #[doc(hidden)]
     /// Configure the default chain
     ///
     /// Exposed for overriding the environment when unit-testing providers
-    pub fn configure(self, configuration: &ProviderConfig) -> Self {
+    pub(crate) fn configure(self, configuration: &ProviderConfig) -> Self {
         Self {
             provider_config: configuration.clone(),
         }

diff --git a/aws/rust-runtime/aws-config/src/default_provider/region.rs b/aws/rust-runtime/aws-config/src/default_provider/region.rs
@@ -45,11 +45,10 @@ pub struct Builder {
 }
 
 impl Builder {
-    #[doc(hidden)]
     /// Configure the default chain
     ///
     /// Exposed for overriding the environment when unit-testing providers
-    pub fn configure(mut self, configuration: &ProviderConfig) -> Self {
+    pub(crate) fn configure(mut self, configuration: &ProviderConfig) -> Self {
         self.env_provider = EnvironmentVariableRegionProvider::new_with_env(configuration.env());
         self.profile_file = self.profile_file.configure(configuration);
         self.imds = self.imds.configure(configuration);

diff --git a/aws/rust-runtime/aws-config/src/environment/credentials.rs b/aws/rust-runtime/aws-config/src/environment/credentials.rs
@@ -58,11 +58,10 @@ impl EnvironmentVariableCredentialsProvider {
         Self::new_with_env(Env::real())
     }
 
-    #[doc(hidden)]
     /// Create a new `EnvironmentVariableCredentialsProvider` with `Env` overridden
     ///
     /// This function is intended for tests that mock out the process environment.
-    pub fn new_with_env(env: Env) -> Self {
+    pub(crate) fn new_with_env(env: Env) -> Self {
         Self { env }
     }
 }

diff --git a/aws/rust-runtime/aws-config/src/environment/region.rs b/aws/rust-runtime/aws-config/src/environment/region.rs
@@ -22,11 +22,10 @@ impl EnvironmentVariableRegionProvider {
         EnvironmentVariableRegionProvider { env: Env::real() }
     }
 
-    #[doc(hidden)]
     /// Create an region provider from a given `Env`
     ///
     /// This method is used for tests that need to override environment variables.
-    pub fn new_with_env(env: Env) -> Self {
+    pub(crate) fn new_with_env(env: Env) -> Self {
         EnvironmentVariableRegionProvider { env }
     }
 }

diff --git a/aws/rust-runtime/aws-config/src/profile/parser.rs b/aws/rust-runtime/aws-config/src/profile/parser.rs
@@ -237,7 +237,7 @@ impl From<ProfileParseError> for ProfileFileLoadError {
     }
 }
 
-#[doc(hidden)]
+/// An error encountered while reading the AWS config file
 #[derive(Debug, Clone)]
 pub struct CouldNotReadProfileFile {
     pub(crate) path: PathBuf,

diff --git a/aws/rust-runtime/aws-inlineable/src/s3_request_id.rs b/aws/rust-runtime/aws-inlineable/src/s3_request_id.rs
@@ -59,8 +59,7 @@ where
 }
 
 /// Applies the extended request ID to a generic error builder
-#[doc(hidden)]
-pub fn apply_extended_request_id(
+pub(crate) fn apply_extended_request_id(
     builder: ErrorMetadataBuilder,
     headers: &Headers,
 ) -> ErrorMetadataBuilder {

diff --git a/aws/rust-runtime/aws-sigv4/src/sign.rs b/aws/rust-runtime/aws-sigv4/src/sign.rs
@@ -5,6 +5,27 @@
 
 //! Functions to create signing keys and calculate signatures.
 
+// macro lifted from aws-smithy-runtime-api—eventually just inline these and delete macro.
+macro_rules! builder_methods {
+    ($fn_name:ident, $arg_name:ident, $ty:ty, $doc:literal, $($tail:tt)+) => {
+        builder_methods!($fn_name, $arg_name, $ty, $doc);
+        builder_methods!($($tail)+);
+    };
+    ($fn_name:ident, $arg_name:ident, $ty:ty, $doc:literal) => {
+        #[doc = $doc]
+        pub fn $fn_name(&mut self, $arg_name: Option<$ty>) -> &mut Self {
+            self.$arg_name = $arg_name;
+            self
+        }
+
+        #[doc = $doc]
+        pub fn $arg_name(mut self, $arg_name: $ty) -> Self {
+            self.$arg_name = Some($arg_name);
+            self
+        }
+    };
+}
+
 /// Support for Sigv4 signing
 pub mod v4;
 

diff --git a/aws/rust-runtime/aws-sigv4/src/sign/v4.rs b/aws/rust-runtime/aws-sigv4/src/sign/v4.rs
@@ -109,7 +109,6 @@ impl<'a, S: Default> SigningParams<'a, S> {
 /// Builder and error for creating [`SigningParams`]
 pub mod signing_params {
     use super::SigningParams;
-    use aws_smithy_runtime_api::builder_methods;
     use aws_smithy_runtime_api::client::identity::Identity;
     use std::error::Error;
     use std::fmt;

diff --git a/aws/rust-runtime/aws-sigv4/src/sign/v4a.rs b/aws/rust-runtime/aws-sigv4/src/sign/v4a.rs
@@ -130,7 +130,6 @@ impl<'a, S: Default> SigningParams<'a, S> {
 /// Builder and error for creating [`SigningParams`]
 pub mod signing_params {
     use super::SigningParams;
-    use aws_smithy_runtime_api::builder_methods;
     use aws_smithy_runtime_api::client::identity::Identity;
     use std::error::Error;
     use std::fmt;

diff --git a/aws/rust-runtime/aws-types/src/lib.rs b/aws/rust-runtime/aws-types/src/lib.rs
@@ -17,7 +17,6 @@
 pub mod app_name;
 pub mod build_metadata;
 pub mod endpoint_config;
-#[doc(hidden)]
 pub mod os_shim_internal;
 pub mod region;
 pub mod request_id;

diff --git a/aws/rust-runtime/aws-types/src/os_shim_internal.rs b/aws/rust-runtime/aws-types/src/os_shim_internal.rs
@@ -45,14 +45,17 @@ impl Default for Fs {
 }
 
 impl Fs {
+    /// Create `Fs` representing a real file system.
     pub fn real() -> Self {
         Fs(fs::Inner::Real)
     }
 
+    /// Create `Fs` from a map of `OsString` to `Vec<u8>`.
     pub fn from_raw_map(fs: HashMap<OsString, Vec<u8>>) -> Self {
         Fs(fs::Inner::Fake(Arc::new(Fake::MapFs(Mutex::new(fs)))))
     }
 
+    /// Create `Fs` from a map of `String` to `Vec<u8>`.
     pub fn from_map(data: HashMap<String, impl Into<Vec<u8>>>) -> Self {
         let fs = data
             .into_iter()
@@ -224,6 +227,7 @@ impl Default for Env {
 }
 
 impl Env {
+    /// Retrieve a value for the given `k` and return `VarError` is that key is not present.
     pub fn get(&self, k: &str) -> Result<String, VarError> {
         use env::Inner;
         match &self.0 {

diff --git a/aws/rust-runtime/aws-types/src/sdk_config.rs b/aws/rust-runtime/aws-types/src/sdk_config.rs
@@ -26,9 +26,9 @@ use aws_smithy_runtime_api::shared::IntoShared;
 pub use aws_smithy_types::retry::RetryConfig;
 pub use aws_smithy_types::timeout::TimeoutConfig;
 
-#[doc(hidden)]
 /// Unified docstrings to keep crates in sync. Not intended for public use
 pub mod unified_docs {
+    /// A macro that generates docs for selected fields of `SdkConfig`.
     #[macro_export]
     macro_rules! docs_for {
         (use_fips) => {
@@ -667,7 +667,6 @@ impl SdkConfig {
         self.timeout_config.as_ref()
     }
 
-    #[doc(hidden)]
     /// Configured sleep implementation
     pub fn sleep_impl(&self) -> Option<SharedAsyncSleep> {
         self.sleep_impl.clone()

diff --git a/aws/sdk/sdk-external-types.toml b/aws/sdk/sdk-external-types.toml
@@ -14,6 +14,7 @@ allowed_external_types = [
     "aws_smithy_eventstream::*",
 
     "aws_smithy_runtime::client::identity::cache::IdentityCache",
+    "aws_smithy_runtime::client::retries::RetryPartition",
 
     "aws_runtime::invocation_id::SharedInvocationIdGenerator",
     "aws_runtime::invocation_id::InvocationIdGenerator",

diff --git a/.../amazon/smithy/rust/codegen/client/smithy/customizations/ResiliencyConfigCustomization.kt b/.../amazon/smithy/rust/codegen/client/smithy/customizations/ResiliencyConfigCustomization.kt
@@ -10,7 +10,6 @@ import software.amazon.smithy.rust.codegen.client.smithy.ClientRustModule
 import software.amazon.smithy.rust.codegen.client.smithy.configReexport
 import software.amazon.smithy.rust.codegen.client.smithy.generators.config.ConfigCustomization
 import software.amazon.smithy.rust.codegen.client.smithy.generators.config.ServiceConfig
-import software.amazon.smithy.rust.codegen.core.rustlang.Attribute
 import software.amazon.smithy.rust.codegen.core.rustlang.rustTemplate
 import software.amazon.smithy.rust.codegen.core.rustlang.writable
 import software.amazon.smithy.rust.codegen.core.smithy.RuntimeType
@@ -65,7 +64,6 @@ class ResiliencyConfigCustomization(codegenContext: ClientCodegenContext) : Conf
                             self.config.load::<#{TimeoutConfig}>()
                         }
 
-                        ##[doc(hidden)]
                         /// Returns a reference to the retry partition contained in this config, if any.
                         ///
                         /// WARNING: This method is unstable and may be removed at any time. Do not rely on this
@@ -248,7 +246,6 @@ class ResiliencyConfigCustomization(codegenContext: ClientCodegenContext) : Conf
                         *codegenScope,
                     )
 
-                    Attribute.DocHidden.render(this)
                     rustTemplate(
                         """
                         /// Set the partition for retry-related state. When clients share a retry partition, they will
@@ -262,7 +259,6 @@ class ResiliencyConfigCustomization(codegenContext: ClientCodegenContext) : Conf
                         *codegenScope,
                     )
 
-                    Attribute.DocHidden.render(this)
                     rustTemplate(
                         """
                         /// Set the partition for retry-related state. When clients share a retry partition, they will

diff --git a/...kotlin/software/amazon/smithy/rust/codegen/client/smithy/generators/OperationGenerator.kt b/...kotlin/software/amazon/smithy/rust/codegen/client/smithy/generators/OperationGenerator.kt
@@ -16,6 +16,7 @@ import software.amazon.smithy.rust.codegen.client.smithy.protocols.ClientHttpBou
 import software.amazon.smithy.rust.codegen.core.rustlang.Attribute
 import software.amazon.smithy.rust.codegen.core.rustlang.Attribute.Companion.derive
 import software.amazon.smithy.rust.codegen.core.rustlang.RustWriter
+import software.amazon.smithy.rust.codegen.core.rustlang.docs
 import software.amazon.smithy.rust.codegen.core.rustlang.implBlock
 import software.amazon.smithy.rust.codegen.core.rustlang.isNotEmpty
 import software.amazon.smithy.rust.codegen.core.rustlang.rust
@@ -77,10 +78,9 @@ open class OperationGenerator(
         )
         Attribute(derive(RuntimeType.Clone, RuntimeType.Default, RuntimeType.Debug)).render(operationWriter)
         Attribute.NonExhaustive.render(operationWriter)
-        Attribute.DocHidden.render(operationWriter)
         operationWriter.rust("pub struct $operationName;")
         operationWriter.implBlock(symbolProvider.toSymbol(operationShape)) {
-            Attribute.DocHidden.render(operationWriter)
+            docs("Creates a new `$operationName`")
             rustBlock("pub fn new() -> Self") {
                 rust("Self")
             }

diff --git a/rust-runtime/aws-smithy-async/src/future/pagination_stream/collect.rs b/rust-runtime/aws-smithy-async/src/future/pagination_stream/collect.rs
@@ -14,7 +14,6 @@ pub(crate) mod sealed {
     ///
     /// Currently the trait may not be implemented by clients so we can make changes in the future
     /// without breaking code depending on it.
-    #[doc(hidden)]
     pub trait Collectable<T> {
         type Collection;