Unverified Commit dbe0dc0e authored by Russell Cohen's avatar Russell Cohen Committed by GitHub
Browse files

Improve documentation on collection builders (#664) 

* Improve documentation on collection builders

Generated builders include "magic" collection methods that will append to the builder. However, the generated names of these methods are confusing because they are often pluralized. To alleviate this, this diff will generate doc hints on these methods to clarify their behavior.

* Update CHANGELOG

* Update CHANGELOG.md
parent 130703da

CHANGELOG.md

+1 −0
Original line number Diff line number Diff line
@@ -9,6 +9,7 @@ vNext (Month Day, Year) 


- (When complete) Add Event Stream support (#653, #xyz)

- (When complete) Add profile file provider for region (#594, #xyz)

- Improve documentation on collection-aware builders (#664)





v0.21 (August 19th, 2021)

aws/sdk-codegen/src/main/kotlin/software/amazon/smithy/rustsdk/FluentClientGenerator.kt

+4 −29
Original line number Diff line number Diff line
@@ -27,6 +27,7 @@ import software.amazon.smithy.rust.codegen.rustlang.stripOuter 
import software.amazon.smithy.rust.codegen.rustlang.writable

import software.amazon.smithy.rust.codegen.smithy.RustCrate

import software.amazon.smithy.rust.codegen.smithy.customize.RustCodegenDecorator

import software.amazon.smithy.rust.codegen.smithy.generators.FluentClientCore

import software.amazon.smithy.rust.codegen.smithy.generators.LibRsCustomization

import software.amazon.smithy.rust.codegen.smithy.generators.LibRsSection

import software.amazon.smithy.rust.codegen.smithy.generators.ProtocolConfig
@@ -77,6 +78,7 @@ class FluentClientGenerator(protocolConfig: ProtocolConfig) { 
    private val model = protocolConfig.model

    private val runtimeConfig = protocolConfig.runtimeConfig

    private val hyperDep = runtimeConfig.awsRuntimeDependency("aws-hyper").copy(optional = true)

    private val core = FluentClientCore(model)



    fun render(writer: RustWriter) {

        writer.rustTemplate(
@@ -192,8 +194,8 @@ class FluentClientGenerator(protocolConfig: ProtocolConfig) { 
                        val memberSymbol = symbolProvider.toSymbol(member)

                        val outerType = memberSymbol.rustType()

                        when (val coreType = outerType.stripOuter<RustType.Option>()) {

                            is RustType.Vec -> renderVecHelper(member, memberName, coreType)

                            is RustType.HashMap -> renderMapHelper(member, memberName, coreType)

                            is RustType.Vec -> with(core) { renderVecHelper(member, memberName, coreType) }

                            is RustType.HashMap -> with(core) { renderMapHelper(member, memberName, coreType) }

                            else -> {

                                val signature = when (coreType) {

                                    is RustType.String,
@@ -222,31 +224,4 @@ class FluentClientGenerator(protocolConfig: ProtocolConfig) { 
            }

        }

    }



    private fun RustWriter.renderMapHelper(member: MemberShape, memberName: String, coreType: RustType.HashMap) {

        documentShape(member, model)

        val k = coreType.key

        val v = coreType.member



        rustBlock("pub fn $memberName(mut self, k: impl Into<${k.render()}>, v: impl Into<${v.render()}>) -> Self") {

            rust(

                """

                self.inner = self.inner.$memberName(k, v);

                self

            """

            )

        }

    }



    private fun RustWriter.renderVecHelper(member: MemberShape, memberName: String, coreType: RustType.Vec) {

        documentShape(member, model)

        rustBlock("pub fn $memberName(mut self, inp: impl Into<${coreType.member.render(true)}>) -> Self") {

            rust(

                """

                self.inner = self.inner.$memberName(inp);

                self

            """

            )

        }

    }

}

codegen/src/main/kotlin/software/amazon/smithy/rust/codegen/smithy/generators/FluentClientCore.kt

0 → 100644
+51 −0
Original line number Diff line number Diff line 
/*

 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

 * SPDX-License-Identifier: Apache-2.0.

 */



package software.amazon.smithy.rust.codegen.smithy.generators



import software.amazon.smithy.model.Model

import software.amazon.smithy.model.shapes.MemberShape

import software.amazon.smithy.rust.codegen.rustlang.RustType

import software.amazon.smithy.rust.codegen.rustlang.RustWriter

import software.amazon.smithy.rust.codegen.rustlang.docs

import software.amazon.smithy.rust.codegen.rustlang.documentShape

import software.amazon.smithy.rust.codegen.rustlang.render

import software.amazon.smithy.rust.codegen.rustlang.rust

import software.amazon.smithy.rust.codegen.rustlang.rustBlock



class FluentClientCore(private val model: Model) {

    fun RustWriter.renderVecHelper(member: MemberShape, memberName: String, coreType: RustType.Vec) {

        docs("Appends an item to `${member.memberName}`.")

        rust("///")

        docs("To override the contents of this collection use [`${member.setterName()}`](Self::${member.setterName()}).")

        documentShape(member, model)

        rustBlock("pub fn $memberName(mut self, inp: impl Into<${coreType.member.render(true)}>) -> Self") {

            rust(

                """

                self.inner = self.inner.$memberName(inp);

                self

            """

            )

        }

    }



    fun RustWriter.renderMapHelper(member: MemberShape, memberName: String, coreType: RustType.HashMap) {

        docs("Adds a key-value pair to `${member.memberName}`.")

        rust("///")

        docs("To override the contents of this collection use [`${member.setterName()}`](Self::${member.setterName()}).")

        documentShape(member, model)

        val k = coreType.key

        val v = coreType.member



        rustBlock("pub fn $memberName(mut self, k: impl Into<${k.render()}>, v: impl Into<${v.render()}>) -> Self") {

            rust(

                """

                self.inner = self.inner.$memberName(k, v);

                self

            """

            )

        }

    }

}

codegen/src/main/kotlin/software/amazon/smithy/rust/codegen/smithy/generators/FluentClientDecorator.kt

+5 −30
Original line number Diff line number Diff line
@@ -38,7 +38,8 @@ class FluentClientDecorator : RustCodegenDecorator { 
    override val name: String = "FluentClient"

    override val order: Byte = 0



    private fun applies(protocolConfig: ProtocolConfig): Boolean = protocolConfig.symbolProvider.config().codegenConfig.includeFluentClient

    private fun applies(protocolConfig: ProtocolConfig): Boolean =

        protocolConfig.symbolProvider.config().codegenConfig.includeFluentClient



    override fun extras(protocolConfig: ProtocolConfig, rustCrate: RustCrate) {

        if (!applies(protocolConfig)) {
@@ -86,6 +87,7 @@ class FluentClientGenerator(protocolConfig: ProtocolConfig) { 
    private val moduleName = protocolConfig.moduleName

    private val moduleUseName = moduleName.replace("-", "_")

    private val humanName = serviceShape.id.name

    private val core = FluentClientCore(model)



    fun render(writer: RustWriter) {

        writer.rustTemplate(
@@ -309,8 +311,8 @@ class FluentClientGenerator(protocolConfig: ProtocolConfig) { 
                        val memberSymbol = symbolProvider.toSymbol(member)

                        val outerType = memberSymbol.rustType()

                        when (val coreType = outerType.stripOuter<RustType.Option>()) {

                            is RustType.Vec -> renderVecHelper(member, memberName, coreType)

                            is RustType.HashMap -> renderMapHelper(member, memberName, coreType)

                            is RustType.Vec -> with(core) { renderVecHelper(member, memberName, coreType) }

                            is RustType.HashMap -> with(core) { renderMapHelper(member, memberName, coreType) }

                            else -> {

                                val signature = when (coreType) {

                                    is RustType.String,
@@ -339,31 +341,4 @@ class FluentClientGenerator(protocolConfig: ProtocolConfig) { 
            }

        }

    }



    private fun RustWriter.renderMapHelper(member: MemberShape, memberName: String, coreType: RustType.HashMap) {

        documentShape(member, model)

        val k = coreType.key

        val v = coreType.member



        rustBlock("pub fn $memberName(mut self, k: impl Into<${k.render()}>, v: impl Into<${v.render()}>) -> Self") {

            rust(

                """

                self.inner = self.inner.$memberName(k, v);

                self

            """

            )

        }

    }



    private fun RustWriter.renderVecHelper(member: MemberShape, memberName: String, coreType: RustType.Vec) {

        documentShape(member, model)

        rustBlock("pub fn $memberName(mut self, inp: impl Into<${coreType.member.render(true)}>) -> Self") {

            rust(

                """

                self.inner = self.inner.$memberName(inp);

                self

            """

            )

        }

    }

}