Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Guidelines implementation: Docs #2286

Closed
2 tasks
eladb opened this issue Apr 15, 2019 · 0 comments · Fixed by #4645
Closed
2 tasks

Guidelines implementation: Docs #2286

eladb opened this issue Apr 15, 2019 · 0 comments · Fixed by #4645
Assignees
@rix0rrr
Labels
in-progress This issue is being actively worked on. package/awscl Cross-cutting issues related to the AWS Construct Library

Comments

@eladb
Copy link
Contributor

eladb commented Apr 15, 2019

  • Implement and apply rule awslint:docs-public-apis: All public APIs should have JSDocs
    --
  • Implement and apply rule awslint:docs-no-duplicates: No duplciate JSDocs should be provided for implementations of intetface members or overrides
@eladb eladb added feature-request A feature should be added or improved. package/awscl Cross-cutting issues related to the AWS Construct Library effort/medium Medium work item – several days of effort and removed feature-request A feature should be added or improved. labels Apr 15, 2019
@eladb eladb added package/awscl Cross-cutting issues related to the AWS Construct Library and removed package/awscl Cross-cutting issues related to the AWS Construct Library labels May 1, 2019
@NGL321 NGL321 added closing-soon This issue will automatically close in 4 days unless further comments are made. pr/needs-community-review This PR needs a review from a Trusted Community Member or Core Team Member. labels Sep 10, 2019
@eladb eladb removed closing-soon This issue will automatically close in 4 days unless further comments are made. effort/medium Medium work item – several days of effort pr/needs-community-review This PR needs a review from a Trusted Community Member or Core Team Member. labels Sep 11, 2019
@eladb eladb assigned rix0rrr and unassigned eladb Oct 23, 2019
rix0rrr added a commit that referenced this issue Oct 23, 2019
@rix0rrr
chore: require docstring on public members
a0b8137 
Many people (still) contribute PRs with undocumented members, or
undocumented classes, or undocumented defaults, because there is no tool
support to check they're not forgetting.

We used to have `@default` checking on props types for L2s, but not for
interfaces that are used INSIDE L2 props structs, or that are used as
props types for non-constructs.

Add two new checks:

* Requirement to document top-level types and public members.
* Requirement to supply `@default` for optional properties on structs.

Which supersede the previous one.

Obviously, we have many currently undocumented APIs which are added
to the ignore list.

Fixes #2286.
@rix0rrr rix0rrr mentioned this issue Oct 23, 2019
Merged
@SomayaB SomayaB added the in-progress This issue is being actively worked on. label Oct 23, 2019
@mergify mergify bot closed this as completed in #4645 Oct 28, 2019
mergify bot pushed a commit that referenced this issue Oct 28, 2019
@rix0rrr @mergify
chore: require docstring on public members (#4645)
dc8061a 
* chore: require docstring on public members

Many people (still) contribute PRs with undocumented members, or
undocumented classes, or undocumented defaults, because there is no tool
support to check they're not forgetting.

We used to have `@default` checking on props types for L2s, but not for
interfaces that are used INSIDE L2 props structs, or that are used as
props types for non-constructs.

Add two new checks:

* Requirement to document top-level types and public members.
* Requirement to supply `@default` for optional properties on structs.

Which supersede the previous one.

Obviously, we have many currently undocumented APIs which are added
to the ignore list.

Fixes #2286.

* Update region-info awslint script

* Update with new undocumented APIs

* More undefaulted props

* Ignore some more undocumented public APIs that got merged in the mean time
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@rix0rrr rix0rrr

Labels
in-progress This issue is being actively worked on. package/awscl Cross-cutting issues related to the AWS Construct Library
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

chore: require docstring on public members aws/aws-cdk
4 participants
@rix0rrr @eladb @NGL321 @SomayaB