diff --git a/packages/jsii-calc/lib/documented.ts b/packages/jsii-calc/lib/documented.ts index c4b6d6b0c8..d88340822c 100644 --- a/packages/jsii-calc/lib/documented.ts +++ b/packages/jsii-calc/lib/documented.ts @@ -12,11 +12,11 @@ export class DocumentedClass { /** * Greet the indicated person. * - * This will print out a friendly greeting intended for - * the indicated person. + * This will print out a friendly greeting intended for the indicated person. * * @param greetee The person to be greeted. - * @returns A number that everyone knows very well + * @returns A number that everyone knows very well and represents the answer + * to the ultimate question */ public greet(greetee: Greetee = {}): number { process.stdout.write(`Hello, ${greetee.name ?? 'world'}\n`); @@ -48,7 +48,8 @@ export interface Greetee { /** * Old class * - * @deprecated Use the new class + * @deprecated Use the new class or the old class whatever you want because + * whatever you like is always the best */ export class Old { /** diff --git a/packages/jsii-pacmak/lib/targets/go/documentation.ts b/packages/jsii-pacmak/lib/targets/go/documentation.ts index 3b411bcbae..f5c4b49697 100644 --- a/packages/jsii-pacmak/lib/targets/go/documentation.ts +++ b/packages/jsii-pacmak/lib/targets/go/documentation.ts @@ -19,27 +19,24 @@ export class Documentation { */ public emit(docs: Docs): void { if (docs.toString() !== '') { - const lines = docs.toString().split('\n'); - for (const line of lines) { - this.code.line(`// ${line}`); - } + this.emitComment(docs.toString()); } if (docs.returns !== '') { - this.code.line(`//`); - this.code.line(`// Returns: ${docs.returns}`); + this.emitComment(); + this.emitComment(`Returns: ${docs.returns}`); } if (docs.example !== '') { - this.code.line(`//`); + this.emitComment(); // TODO: Translate code examples to Go with Rosetta (not implemented there yet) - this.code.line('// TODO: EXAMPLE'); - this.code.line(`//`); + this.emitComment('TODO: EXAMPLE'); + this.emitComment(); } if (docs.link !== '') { - this.code.line(`// See: ${docs.link}`); - this.code.line(`//`); + this.emitComment(`See: ${docs.link}`); + this.emitComment(); } this.emitStability(docs); @@ -49,13 +46,19 @@ export class Documentation { const stability = docs.stability; if (stability && this.shouldMentionStability(docs)) { if (docs.deprecated) { - this.code.line(`// Deprecated: ${docs.deprecationReason}`); + this.emitComment(`Deprecated: ${docs.deprecationReason}`); } else { - this.code.line(`// ${this.code.toPascalCase(stability)}.`); + this.emitComment(`${this.code.toPascalCase(stability)}.`); } } } + private emitComment(text = '') { + for (const line of text.split('\n')) { + this.code.line(`// ${line}`); + } + } + private shouldMentionStability(docs: Docs): boolean { const s = docs.stability; // Don't render "stable" or "external", those are both stable by implication diff --git a/packages/jsii-pacmak/test/generated-code/__snapshots__/target-dotnet.test.ts.snap b/packages/jsii-pacmak/test/generated-code/__snapshots__/target-dotnet.test.ts.snap index 319f66a73f..1fc0591dc3 100644 --- a/packages/jsii-pacmak/test/generated-code/__snapshots__/target-dotnet.test.ts.snap +++ b/packages/jsii-pacmak/test/generated-code/__snapshots__/target-dotnet.test.ts.snap @@ -4891,10 +4891,10 @@ namespace Amazon.JSII.Tests.CalculatorNamespace /// Greet the indicated person. /// The person to be greeted. - /// A number that everyone knows very well + /// A number that everyone knows very well and represents the answer + /// to the ultimate question /// - /// This will print out a friendly greeting intended for - /// the indicated person. + /// This will print out a friendly greeting intended for the indicated person. /// [JsiiMethod(name: "greet", returnsJson: "{\\"type\\":{\\"primitive\\":\\"number\\"}}", parametersJson: "[{\\"docs\\":{\\"summary\\":\\"The person to be greeted.\\"},\\"name\\":\\"greetee\\",\\"optional\\":true,\\"type\\":{\\"fqn\\":\\"jsii-calc.Greetee\\"}}]")] public virtual double Greet(Amazon.JSII.Tests.CalculatorNamespace.IGreetee? greetee = null) @@ -11339,7 +11339,7 @@ namespace Amazon.JSII.Tests.CalculatorNamespace /// Stability: Deprecated /// [JsiiClass(nativeType: typeof(Amazon.JSII.Tests.CalculatorNamespace.Old), fullyQualifiedName: "jsii-calc.Old")] - [System.Obsolete("Use the new class")] + [System.Obsolete("Use the new class or the old class whatever you want because whatever you like is always the best")] public class Old : DeputyBase { public Old(): base(new DeputyProps(System.Array.Empty())) diff --git a/packages/jsii-pacmak/test/generated-code/__snapshots__/target-go.test.ts.snap b/packages/jsii-pacmak/test/generated-code/__snapshots__/target-go.test.ts.snap index dab69630b2..53d132da6e 100644 --- a/packages/jsii-pacmak/test/generated-code/__snapshots__/target-go.test.ts.snap +++ b/packages/jsii-pacmak/test/generated-code/__snapshots__/target-go.test.ts.snap @@ -3027,9 +3027,9 @@ type CalculatorIface interface { // \`\`\` // // I will repeat this example again, but in an @example tag. -// +// // TODO: EXAMPLE -// +// // Struct proxy type Calculator struct { // (deprecated) The value. @@ -3782,11 +3782,11 @@ type ClassWithDocsIface interface { // This class has docs. // // The docs are great. They're a bunch of tags. -// +// // TODO: EXAMPLE -// +// // See: https://aws.amazon.com/ -// +// // Struct proxy type ClassWithDocs struct { } @@ -3969,7 +3969,7 @@ type ConfusingToJacksonIface interface { // This tries to confuse Jackson by having overloaded property setters. // See: https://github.com/aws/aws-cdk/issues/4080 -// +// // Struct proxy type ConfusingToJackson struct { UnionProperty interface{} \`json:"unionProperty"\` @@ -6371,7 +6371,7 @@ type IFriendlierIface interface { // Say farewell. Farewell() string // Say goodbye. - // + // // Returns: A goodbye blessing. Goodbye() string } @@ -6990,7 +6990,7 @@ func (i *IPublicInterface2) Ciao() string { // Generates random numbers. type IRandomNumberGeneratorIface interface { // Returns another random number. - // + // // Returns: A random number. Next() float64 } @@ -8705,7 +8705,7 @@ type JsonFormatterIface interface { // Make sure structs are un-decorated on the way in. // See: https://github.com/aws/aws-cdk/issues/5066 -// +// // Struct proxy type JsonFormatter struct { } @@ -9853,7 +9853,8 @@ type OldIface interface { } // Old class. -// Deprecated: Use the new class +// Deprecated: Use the new class or the old class whatever you want because +// whatever you like is always the best // Struct proxy type Old struct { } @@ -10071,7 +10072,7 @@ type OverridableProtectedMemberIface interface { } // See: https://github.com/aws/jsii/issues/903 -// +// // Struct proxy type OverridableProtectedMember struct { OverrideReadOnly string \`json:"overrideReadOnly"\` @@ -11081,10 +11082,10 @@ type ReturnsPrivateImplementationOfInterfaceIface interface { } // Helps ensure the JSII kernel & runtime cooperate correctly when an un-exported instance of a class is returned with a declared type that is an exported interface, and the instance inherits from an exported class. -// +// // Returns: an instance of an un-exported class that extends \`ExportedBaseClass\`, declared as \`IPrivatelyImplemented\`. // See: https://github.com/aws/jsii/issues/320 -// +// // Struct proxy type ReturnsPrivateImplementationOfInterface struct { PrivateImplementation IPrivatelyImplementedIface \`json:"privateImplementation"\` @@ -12947,7 +12948,7 @@ type UmaskCheckIface interface { // Checks the current file permissions are cool (no funky UMASK down-scoping happened). // See: https://github.com/aws/jsii/issues/1765 -// +// // Struct proxy type UmaskCheck struct { } @@ -13834,7 +13835,7 @@ type OuterClassIface interface { // Checks that classes can self-reference during initialization. // See: : https://github.com/aws/jsii/pull/1706 -// +// // Struct proxy type OuterClass struct { InnerClass InnerClassIface \`json:"innerClass"\` diff --git a/packages/jsii-pacmak/test/generated-code/__snapshots__/target-java.test.ts.snap b/packages/jsii-pacmak/test/generated-code/__snapshots__/target-java.test.ts.snap index 4af33898ae..3edb60643a 100644 --- a/packages/jsii-pacmak/test/generated-code/__snapshots__/target-java.test.ts.snap +++ b/packages/jsii-pacmak/test/generated-code/__snapshots__/target-java.test.ts.snap @@ -7402,10 +7402,10 @@ public class DocumentedClass extends software.amazon.jsii.JsiiObject { /** * Greet the indicated person. *

- * This will print out a friendly greeting intended for - * the indicated person. + * This will print out a friendly greeting intended for the indicated person. *

- * @return A number that everyone knows very well + * @return A number that everyone knows very well and represents the answer + * to the ultimate question * @param greetee The person to be greeted. */ @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable) @@ -7416,10 +7416,10 @@ public class DocumentedClass extends software.amazon.jsii.JsiiObject { /** * Greet the indicated person. *

- * This will print out a friendly greeting intended for - * the indicated person. + * This will print out a friendly greeting intended for the indicated person. *

- * @return A number that everyone knows very well + * @return A number that everyone knows very well and represents the answer + * to the ultimate question */ @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Stable) public @org.jetbrains.annotations.NotNull java.lang.Number greet() { @@ -14455,7 +14455,8 @@ package software.amazon.jsii.tests.calculator; /** * (deprecated) Old class. *

- * @deprecated Use the new class + * @deprecated Use the new class or the old class whatever you want because + * whatever you like is always the best */ @javax.annotation.Generated(value = "jsii-pacmak") @software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Deprecated) diff --git a/packages/jsii-pacmak/test/generated-code/__snapshots__/target-python.test.ts.snap b/packages/jsii-pacmak/test/generated-code/__snapshots__/target-python.test.ts.snap index 1a7b07282e..5116dfedff 100644 --- a/packages/jsii-pacmak/test/generated-code/__snapshots__/target-python.test.ts.snap +++ b/packages/jsii-pacmak/test/generated-code/__snapshots__/target-python.test.ts.snap @@ -3272,12 +3272,14 @@ class DocumentedClass(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.DocumentedCl def greet(self, *, name: typing.Optional[builtins.str] = None) -> jsii.Number: """Greet the indicated person. - This will print out a friendly greeting intended for - the indicated person. + This will print out a friendly greeting intended for the indicated person. :param name: The name of the greetee. Default: world - :return: A number that everyone knows very well + :return: + + A number that everyone knows very well and represents the answer + to the ultimate question """ greetee = Greetee(name=name) @@ -6138,7 +6140,10 @@ class ObjectWithPropertyProvider( class Old(metaclass=jsii.JSIIMeta, jsii_type="jsii-calc.Old"): """(deprecated) Old class. - :deprecated: Use the new class + :deprecated: + + Use the new class or the old class whatever you want because + whatever you like is always the best :stability: deprecated """