doc: construct properties using protected getters not marked in the docs
- Dominant language
- TypeScript
- Stars
- 12.9k
- Forks
- 4.6k
- Avg merge
- 1d 19h
- Merged PRs (30d)
- 71
Description
### Describe the issue
Some examples:
### aws-cdk-lib.aws_secretsmanager.Secret, `arnForPolicies`
Docs: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_secretsmanager.Secret.html#properties (note that `arnForPolicies` is not marked as `protected` anywhere in the table)
Specific property (`arnForPolicies`): not noted in the docs for the property either https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_secretsmanager.Secret.html#arnforpolicies
Code: https://github.com/aws/aws-cdk/blob/v2.85.0/packages/aws-cdk-lib/aws-secretsmanager/lib/secret.ts#L452
Usage:
```typescript
import * as cdk from 'aws-cdk-lib';
import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
const app = new cdk.App();
const stack = new cdk.Stack(app, 'MyStack');
const secret = new secretsmanager.Secret(stack, 'MySecret', {});
secret.arnForPolicies;
```
Running with `npx ts-node` gives:
```
error TS2445: Property 'arnForPolicies' is protected and only accessible within class 'SecretBase' and its subclasses.
6 secret.arnForPolicies;
~~~~~~~~~~~~~~
```
### aws-cdk-lib.aws_dynamodb.Table, `hasIndex`
Docs: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_dynamodb.Table.html#properties (note that `hasIndex` is not marked as `protected` anywhere in the table)
Specific property: (`hasIndex`): not noted in the docs for the property either https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_dynamodb.Table.html#hasindex
Code: https://github.com/aws/aws-cdk/blob/v2.85.0/packages/aws-cdk-lib/aws-dynamodb/lib/table.ts#L1723
Usage:
```typescript
import * as cdk from 'aws-cdk-lib';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
const app = new cdk.App();
const stack = new cdk.Stack(app, 'MyStack');
const table = new dynamodb.Table(stack, 'MyTable', {
partitionKey: {
name: 'id',
type: dynamodb.AttributeType.STRING,
},
});
table.hasIndex;
```
Running with `npx ts-node` gives:
```
error TS2445: Property 'hasIndex' is protected and only accessible within class 'Table' and its subclasses.
11 table.hasIndex;
~~~~~~~~
```
Probably affects all (or many) of https://github.com/search?q=repo%3Aaws%2Faws-cdk+%22protected+get%22&type=code as the root cause appears to be something in the docs generation.
I think it does make sense for any protected properties (and methods) to be included in the docs, as I might rely on them in a subclass I write, but the docs should mark them as protected, or otherwise make it clear that they aren't public.
### Links
- https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_secretsmanager.Secret.html
- https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_dynamodb.Table.html
And probably all of:
- https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CfnResource.html#cfnproperties
- https://github.com/aws/aws-cdk/blob/v2.85.0/packages/aws-cdk-lib/core/lib/cfn-resource.ts#L483
- https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CfnResource.html#updatedproperitesspan-classapi-icon-api-icon-deprecated-titlethis-api-element-is-deprecated-its-use-is-not-recommended%EF%B8%8Fspan
- https://github.com/aws/aws-cdk/blob/v2.85.0/packages/aws-cdk-lib/core/lib/cfn-resource.ts#L509
- https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CfnResource.html#updatedproperties
- https://github.com/aws/aws-cdk/blob/v2.85.0/packages/aws-cdk-lib/core/lib/cfn-resource.ts#L519
- https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizer.html#stackspan-classapi-icon-api-icon-deprecated-titlethis-api-element-is-deprecated-its-use-is-not-recommended%EF%B8%8Fspan
- https://github.com/aws/aws-cdk/blob/v2.85.0/packages/aws-cdk-lib/core/lib/stack-synthesizers/default-synthesizer.ts#L409
- https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.StackSynthesizer.html#boundstack
- https://github.com/aws/aws-cdk/blob/v2.85.0/packages/aws-cdk-lib/core/lib/stack-synthesizers/stack-synthesizer.ts#L145
Contributor guide
Research direction
Start by comparing the protected getters in packages/aws-cdk-lib/aws-secretsmanager/lib/secret.ts, aws-dynamodb/lib/table.ts, and the listed core stack-synthesizer and CfnResource files with their generated API documentation. Trace the documentation-generation path for protected members and verify it against the provided examples. Done means protected properties and methods are clearly marked as protected wherever they appear in the generated docs.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, typescript
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100