Skip to content

Commit 094a215

Browse files
author
Elad Ben-Israel
authored
fix(docs): improve docs rendering (#303)
Fixes #301: reject non-optional arguments after optional arguments Fixes #298: show default values for optional properties Fixes #302: omit "abstract" from interface properties (they are by definition abstract) Fixes #300: indicate optionals with "optional" instead of "or undefined" Fixes #299: render multiple jsdoc lines as multiple lines in sphinx
1 parent 43fb16a commit 094a215

File tree

19 files changed

+1362
-126
lines changed

19 files changed

+1362
-126
lines changed

‎packages/jsii-calc/lib/compliance.ts‎

Lines changed: 64 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -241,7 +241,7 @@ export class RuntimeTypeChecking {
241241
arg1; arg2; arg3;
242242
}
243243

244-
public methodWithDefaultedArguments(arg1: number = 2, arg2: string, arg3: Date = new Date()) {
244+
public methodWithDefaultedArguments(arg1: number = 2, arg2?: string, arg3: Date = new Date()) {
245245
arg1; arg2; arg3;
246246
}
247247

@@ -258,7 +258,7 @@ export class OptionalConstructorArgument {
258258

259259
export class DefaultedConstructorArgument {
260260
public constructor(public readonly arg1: number = 2,
261-
public readonly arg2: string,
261+
public readonly arg2?: string,
262262
public readonly arg3: Date = new Date()) {}
263263
}
264264

@@ -994,3 +994,65 @@ export interface NullShouldBeTreatedAsUndefinedData {
994994
arrayWithThreeElementsAndUndefinedAsSecondArgument: any[];
995995
}
996996

997+
/**
998+
* jsii#298: show default values in sphinx documentation, and respect newlines.
999+
**/
1000+
export interface LoadBalancedFargateServiceProps {
1001+
/**
1002+
* The number of cpu units used by the task.
1003+
* Valid values, which determines your range of valid values for the memory parameter:
1004+
* 256 (.25 vCPU) - Available memory values: 0.5GB, 1GB, 2GB
1005+
* 512 (.5 vCPU) - Available memory values: 1GB, 2GB, 3GB, 4GB
1006+
* 1024 (1 vCPU) - Available memory values: 2GB, 3GB, 4GB, 5GB, 6GB, 7GB, 8GB
1007+
* 2048 (2 vCPU) - Available memory values: Between 4GB and 16GB in 1GB increments
1008+
* 4096 (4 vCPU) - Available memory values: Between 8GB and 30GB in 1GB increments
1009+
*
1010+
* This default is set in the underlying FargateTaskDefinition construct.
1011+
*
1012+
* @default 256
1013+
*/
1014+
cpu?: string;
1015+
1016+
/**
1017+
* The amount (in MiB) of memory used by the task.
1018+
*
1019+
* This field is required and you must use one of the following values, which determines your range of valid values
1020+
* for the cpu parameter:
1021+
*
1022+
* 0.5GB, 1GB, 2GB - Available cpu values: 256 (.25 vCPU)
1023+
*
1024+
* 1GB, 2GB, 3GB, 4GB - Available cpu values: 512 (.5 vCPU)
1025+
*
1026+
* 2GB, 3GB, 4GB, 5GB, 6GB, 7GB, 8GB - Available cpu values: 1024 (1 vCPU)
1027+
*
1028+
* Between 4GB and 16GB in 1GB increments - Available cpu values: 2048 (2 vCPU)
1029+
*
1030+
* Between 8GB and 30GB in 1GB increments - Available cpu values: 4096 (4 vCPU)
1031+
*
1032+
* This default is set in the underlying FargateTaskDefinition construct.
1033+
*
1034+
* @default 512
1035+
*/
1036+
memoryMiB?: string;
1037+
1038+
/**
1039+
* The container port of the application load balancer attached to your Fargate service. Corresponds to container port mapping.
1040+
*
1041+
* @default 80
1042+
*/
1043+
containerPort?: number;
1044+
1045+
/**
1046+
* Determines whether the Application Load Balancer will be internet-facing
1047+
*
1048+
* @default true
1049+
*/
1050+
publicLoadBalancer?: boolean;
1051+
1052+
/**
1053+
* Determines whether your Fargate Service will be assigned a public IP address.
1054+
*
1055+
* @default false
1056+
*/
1057+
publicTasks?: boolean;
1058+
}

‎packages/jsii-calc/test/assembly.jsii‎

Lines changed: 80 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1114,6 +1114,7 @@
11141114
{
11151115
"name": "arg2",
11161116
"type": {
1117+
"optional": true,
11171118
"primitive": "string"
11181119
}
11191120
},
@@ -1138,16 +1139,17 @@
11381139
},
11391140
{
11401141
"immutable": true,
1141-
"name": "arg2",
1142+
"name": "arg3",
11421143
"type": {
1143-
"primitive": "string"
1144+
"primitive": "date"
11441145
}
11451146
},
11461147
{
11471148
"immutable": true,
1148-
"name": "arg3",
1149+
"name": "arg2",
11491150
"type": {
1150-
"primitive": "date"
1151+
"optional": true,
1152+
"primitive": "string"
11511153
}
11521154
}
11531155
]
@@ -1996,6 +1998,78 @@
19961998
}
19971999
]
19982000
},
2001+
"jsii-calc.LoadBalancedFargateServiceProps": {
2002+
"assembly": "jsii-calc",
2003+
"datatype": true,
2004+
"docs": {
2005+
"comment": "jsii#298: show default values in sphinx documentation, and respect newlines."
2006+
},
2007+
"fqn": "jsii-calc.LoadBalancedFargateServiceProps",
2008+
"kind": "interface",
2009+
"name": "LoadBalancedFargateServiceProps",
2010+
"properties": [
2011+
{
2012+
"abstract": true,
2013+
"docs": {
2014+
"comment": "The container port of the application load balancer attached to your Fargate service. Corresponds to container port mapping.",
2015+
"default": "80"
2016+
},
2017+
"name": "containerPort",
2018+
"type": {
2019+
"optional": true,
2020+
"primitive": "number"
2021+
}
2022+
},
2023+
{
2024+
"abstract": true,
2025+
"docs": {
2026+
"comment": "The number of cpu units used by the task.\nValid values, which determines your range of valid values for the memory parameter:\n256 (.25 vCPU) - Available memory values: 0.5GB, 1GB, 2GB\n512 (.5 vCPU) - Available memory values: 1GB, 2GB, 3GB, 4GB\n1024 (1 vCPU) - Available memory values: 2GB, 3GB, 4GB, 5GB, 6GB, 7GB, 8GB\n2048 (2 vCPU) - Available memory values: Between 4GB and 16GB in 1GB increments\n4096 (4 vCPU) - Available memory values: Between 8GB and 30GB in 1GB increments\n\nThis default is set in the underlying FargateTaskDefinition construct.",
2027+
"default": "256"
2028+
},
2029+
"name": "cpu",
2030+
"type": {
2031+
"optional": true,
2032+
"primitive": "string"
2033+
}
2034+
},
2035+
{
2036+
"abstract": true,
2037+
"docs": {
2038+
"comment": "The amount (in MiB) of memory used by the task.\n\nThis field is required and you must use one of the following values, which determines your range of valid values\nfor the cpu parameter:\n\n0.5GB, 1GB, 2GB - Available cpu values: 256 (.25 vCPU)\n\n1GB, 2GB, 3GB, 4GB - Available cpu values: 512 (.5 vCPU)\n\n2GB, 3GB, 4GB, 5GB, 6GB, 7GB, 8GB - Available cpu values: 1024 (1 vCPU)\n\nBetween 4GB and 16GB in 1GB increments - Available cpu values: 2048 (2 vCPU)\n\nBetween 8GB and 30GB in 1GB increments - Available cpu values: 4096 (4 vCPU)\n\nThis default is set in the underlying FargateTaskDefinition construct.",
2039+
"default": "512"
2040+
},
2041+
"name": "memoryMiB",
2042+
"type": {
2043+
"optional": true,
2044+
"primitive": "string"
2045+
}
2046+
},
2047+
{
2048+
"abstract": true,
2049+
"docs": {
2050+
"comment": "Determines whether the Application Load Balancer will be internet-facing",
2051+
"default": "true"
2052+
},
2053+
"name": "publicLoadBalancer",
2054+
"type": {
2055+
"optional": true,
2056+
"primitive": "boolean"
2057+
}
2058+
},
2059+
{
2060+
"abstract": true,
2061+
"docs": {
2062+
"comment": "Determines whether your Fargate Service will be assigned a public IP address.",
2063+
"default": "false"
2064+
},
2065+
"name": "publicTasks",
2066+
"type": {
2067+
"optional": true,
2068+
"primitive": "boolean"
2069+
}
2070+
}
2071+
]
2072+
},
19992073
"jsii-calc.Multiply": {
20002074
"assembly": "jsii-calc",
20012075
"base": {
@@ -2713,6 +2787,7 @@
27132787
{
27142788
"name": "arg2",
27152789
"type": {
2790+
"optional": true,
27162791
"primitive": "string"
27172792
}
27182793
},
@@ -3537,5 +3612,5 @@
35373612
}
35383613
},
35393614
"version": "0.7.8",
3540-
"fingerprint": "FZk0ePQ2XUte84CmnOjU3PPCl6QUA88ke6wHIJKhyzo="
3615+
"fingerprint": "3UAOWGBZzphiNp40hKAbXcsM27uWdwmXnbiPU74ZroU="
35413616
}

‎packages/jsii-pacmak/lib/targets/sphinx.ts‎

Lines changed: 17 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -254,12 +254,12 @@ class SphinxDocsGenerator extends Generator {
254254
//
255255
// Properties
256256

257-
protected onProperty(_cls: spec.ClassType, prop: spec.Property) {
258-
this.renderProperty(prop);
257+
protected onProperty(cls: spec.ClassType, prop: spec.Property) {
258+
this.renderProperty(cls, prop);
259259
}
260260

261-
protected onStaticProperty(_cls: spec.ClassType, prop: spec.Property) {
262-
this.renderProperty(prop);
261+
protected onStaticProperty(cls: spec.ClassType, prop: spec.Property) {
262+
this.renderProperty(cls, prop);
263263
}
264264

265265
//
@@ -357,8 +357,8 @@ class SphinxDocsGenerator extends Generator {
357357
this.onInterfaceMethod(ifc, overload);
358358
}
359359

360-
protected onInterfaceProperty(_ifc: spec.InterfaceType, property: spec.Property) {
361-
this.renderProperty(property);
360+
protected onInterfaceProperty(ifc: spec.InterfaceType, property: spec.Property) {
361+
this.renderProperty(ifc, property);
362362
}
363363

364364
private renderInheritedMembers(entity: spec.ClassType | spec.InterfaceType) {
@@ -373,7 +373,7 @@ class SphinxDocsGenerator extends Generator {
373373
}
374374
}
375375
for (const property of entities.properties) {
376-
this.renderProperty(property, source);
376+
this.renderProperty(entity, property, source);
377377
}
378378
}
379379
}
@@ -543,13 +543,13 @@ class SphinxDocsGenerator extends Generator {
543543
}
544544

545545
private renderDocsLine(element: spec.Documentable) {
546-
const doclines = this.renderDocs(element, false);
546+
const doclines = this.renderDocs(element, true);
547547
if (doclines.length === 0) {
548548
return;
549549
}
550550

551551
this.code.line();
552-
doclines.split('\n').forEach(line => this.code.line(line));
552+
doclines.split('\n').forEach(line => this.code.line(line + '\n'));
553553

554554
if (element.docs && element.docs.link) {
555555
this.code.line(element.docs.link);
@@ -618,7 +618,7 @@ class SphinxDocsGenerator extends Generator {
618618
} else {
619619
throw new Error('Unexpected type ref');
620620
}
621-
if (type.optional) { result.ref = `${result.ref} or \`\`undefined\`\``; }
621+
if (type.optional) { result.ref = `${result.ref} *(optional)*`; }
622622
return result;
623623

624624
// Wrap a string between parenthesis if it contains " or "
@@ -628,7 +628,7 @@ class SphinxDocsGenerator extends Generator {
628628
}
629629
}
630630

631-
private renderProperty(prop: spec.Property, inheritedFrom?: string) {
631+
private renderProperty(parent: spec.TypeBase, prop: spec.Property, inheritedFrom?: string) {
632632
this.code.line();
633633
const type = this.renderTypeRef(prop.type);
634634
this.code.openBlock(`.. py:attribute:: ${prop.name}`);
@@ -651,9 +651,14 @@ class SphinxDocsGenerator extends Generator {
651651
this.code.line();
652652
}
653653
const readonly = prop.immutable ? ' *(readonly)*' : '';
654-
const abs = prop.abstract ? ' *(abstract)*' : '';
654+
const abs = (parent.kind !== spec.TypeKind.Interface && prop.abstract) ? ' *(abstract)*' : '';
655655
const stat = prop.static ? ' *(static)*' : '';
656656
this.code.line(`:type: ${type.ref}${readonly}${abs}${stat}`);
657+
658+
if (prop.docs && prop.docs.default) {
659+
this.code.line(`:default: ${prop.docs.default}`);
660+
}
661+
657662
this.code.closeBlock();
658663
}
659664

‎packages/jsii-pacmak/test/expected.jsii-calc-base/sphinx/_scope_jsii-calc-base.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,7 @@ Base
153153
A base class.
154154

155155

156+
156157
:abstract: Yes
157158

158159
.. py:method:: typeName() -> any
@@ -193,13 +194,13 @@ BaseProps (interface)
193194

194195
.. py:attribute:: bar
195196
196-
:type: string *(abstract)*
197+
:type: string
197198

198199

199200
.. py:attribute:: foo
200201
201202
*Inherited from* :py:attr:`@scope/jsii-calc-base-of-base.VeryBaseProps <@scope/jsii-calc-base-of-base.VeryBaseProps.foo>`
202203

203-
:type: :py:class:`@scope/jsii-calc-base-of-base.Very`\ *(abstract)*
204+
:type: :py:class:`@scope/jsii-calc-base-of-base.Very`\
204205

205206

0 commit comments

Comments
 (0)