The Wayback Machine - https://web.archive.org/web/20200829130101/https://github.com/falconry/falcon/issues/1638
Skip to content

/ falcon

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.

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

Codify style for doctring summary lines #1638

Open
kgriffs opened this issue Jan 14, 2020 · 3 comments
Open

Codify style for doctring summary lines #1638

kgriffs opened this issue Jan 14, 2020 · 3 comments
Labels
community documentation good first issue needs contributor
Milestone
Version 3.0

Comments

@kgriffs
Copy link
Member

@kgriffs kgriffs commented Jan 14, 2020

Currently, we ask contributors to strive for consistency with existing code, but it would be helpful to clarify the following regarding docstrings:

  • Docstrings should begin with a short (~70 characters or less) summary line that ends in a period.
  • The summary line should begin immediately after the opening quotes (do not add a line break before the summary line)
  • The summary line should describe what it is if it is a class (e.g., "An asynchronous, file-like object for reading ASGI streams.")
  • The summary line should describe what it does when called, if it is a function, structured as an imperative (e.g., "Delete a header that was previously set for this response.")

We will need two patches to address this issue:

  • Update CONTRIBUTING.md to include the guidelines above
  • Fix up any existing docstrings to provide a baseline of consistency going forward
@kgriffs kgriffs added this to the Version 3.0 milestone Jan 14, 2020
@kgriffs kgriffs mentioned this issue Jan 14, 2020
Merged
@danilito19
Copy link

@danilito19 danilito19 commented Aug 17, 2020

@kgriffs I can help in updating CONTRIBUTING.md
@danilito19 danilito19 mentioned this issue Aug 17, 2020
Open
0 of 13 tasks complete
@vytas7
Copy link
Member

@vytas7 vytas7 commented Aug 17, 2020

Hi @danilito19 ,
Awesome, thanks for your contribution ❗

Could you attempt the second part too? It shouldn't be too hard either, mostly mechanical grepping plus some touch ups in case people (for instance, me 😈 ) happened to merge non-conforming docstrings.
@danilito19
Copy link

@danilito19 danilito19 commented Aug 18, 2020

Absolutely! I thought I needed a bit more understanding on the functions but I can grep and update without changing the wording / meaning.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
community documentation good first issue needs contributor
Projects
None yet
Milestone
Version 3.0
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants
@kgriffs @vytas7 @danilito19
You can’t perform that action at this time.