aws / aws/aws-cdk

doc: construct properties using protected getters not marked in the docs

Open
#26,079 1 comment 0 reactions 0 assignees View on GitHub
@aws-cdk/aws-secretsmanager documentation effort/medium feature-request p2
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.