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

chore: require docstring on public members #4645

Merged
merged 9 commits into from
Oct 28, 2019
Merged

chore: require docstring on public members #4645

merged 9 commits into from
Oct 28, 2019

Conversation

rix0rrr
Copy link
Contributor

@rix0rrr rix0rrr commented Oct 23, 2019

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.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

@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 self-assigned this Oct 23, 2019
@mergify
Copy link
Contributor

mergify bot commented Oct 23, 2019

Thanks so much for taking the time to contribute to the AWS CDK ❤️

We will shortly assign someone to review this pull request and help get it
merged. In the meantime, please take a minute to make sure you follow this
checklist:

  • PR title type(scope): text
    • type: fix, feat, refactor go into CHANGELOG, chore is hidden
    • scope: name of module without aws- or cdk- prefix or postfix (e.g. s3 instead of aws-s3-deployment)
    • text: use all lower-case, do not end with a period, do not include issue refs
  • PR Description
    • Rationale: describe rationale of change and approach taken
    • Issues: indicate issues fixed via: fixes #xxx or closes #xxx
    • Breaking?: last paragraph: BREAKING CHANGE: <describe what changed + link for details>
  • Testing
    • Unit test added. Prefer to add a new test rather than modify existing tests
    • CLI or init templates change? Re-run/add CLI integration tests
  • Documentation
    • README: update module README to describe new features
    • API docs: public APIs must be documented. Copy from official AWS docs when possible
    • Design: for significant features, follow design process

@aws-cdk-automation
Copy link
Collaborator

AWS CodeBuild CI Report

  • Result: FAILED
  • Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

@aws-cdk-automation
Copy link
Collaborator

AWS CodeBuild CI Report

  • Result: SUCCEEDED
  • Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

@SomayaB SomayaB added the contribution/core This is a PR that came from AWS. label Oct 23, 2019
eladb
eladb approved these changes Oct 25, 2019
View reviewed changes
Copy link
Contributor

@eladb eladb left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to kick off a program to get rid of all these exclusions.

@mergify
Copy link
Contributor

mergify bot commented Oct 25, 2019

Thank you for contributing! Your pull request is now being automatically merged.

@aws-cdk-automation
Copy link
Collaborator

AWS CodeBuild CI Report

  • Result: FAILED
  • Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

@aws-cdk-automation
Copy link
Collaborator

AWS CodeBuild CI Report

  • Result: SUCCEEDED
  • Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

@aws-cdk-automation
Copy link
Collaborator

AWS CodeBuild CI Report

  • Result: FAILED
  • Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

@aws-cdk-automation
Copy link
Collaborator

AWS CodeBuild CI Report

  • Result: FAILED
  • Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

@aws-cdk-automation
Copy link
Collaborator

AWS CodeBuild CI Report

  • Result: FAILED
  • Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

@aws-cdk-automation
Copy link
Collaborator

AWS CodeBuild CI Report

  • Result: SUCCEEDED
  • Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

@aws-cdk-automation
Copy link
Collaborator

AWS CodeBuild CI Report

  • Result: SUCCEEDED
  • Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

@mergify mergify bot merged commit dc8061a into master Oct 28, 2019
@mergify mergify bot deleted the huijbers/require-docstrings branch October 28, 2019 17:48
@jogold jogold mentioned this pull request Oct 29, 2019
Closed
@trivikr trivikr mentioned this pull request Nov 27, 2019
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@eladb eladb eladb approved these changes

@RomainMuller RomainMuller Awaiting requested review from RomainMuller

@shivlaks shivlaks Awaiting requested review from shivlaks

@garnaat garnaat Awaiting requested review from garnaat

@nija-at nija-at Awaiting requested review from nija-at

@skinny85 skinny85 Awaiting requested review from skinny85

@SoManyHs SoManyHs Awaiting requested review from SoManyHs

Assignees

@rix0rrr rix0rrr

Labels
contribution/core This is a PR that came from AWS.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Guidelines implementation: Docs
4 participants
@rix0rrr @aws-cdk-automation @eladb @SomayaB