search

aws / aws-cdk

The AWS Cloud Development Kit is a framework for defining cloud infrastructure in code
https://aws.amazon.com/cdk
Apache License 2.0
11.64k stars 3.91k forks source link

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

Open plumdog opened 1 year ago

plumdog commented 1 year ago

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:

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:

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

And probably all of:

pahud commented 1 year ago

https://github.com/aws/aws-cdk/blob/a79794e3f2609e6efa5cf659eec039964a8ad61c/packages/aws-cdk-lib/aws-secretsmanager/lib/secret.ts#L452

Yes I agree we should mark it as protected in the doc.