Opened 4 years ago

Closed 4 years ago

#6537 enhancement closed fixed (fixed)

Update coding-standard to reflect that documentation should be sentence per line.

Reported by: Tom Prince Owned by: Tom Prince
Priority: normal Milestone:
Component: core Keywords: policy documentation
Cc: Branch: branches/sentence-per-line-6537
branch-diff, diff-cov, branch-cov, buildbot
Author: tomprince

Description (last modified by Jean-Paul Calderone)

This results in diffs that are easier to read, making documentation maintenance easier.

Change History (9)

comment:1 Changed 4 years ago by Tom Prince

I wonder if this should also apply to docstrings and other multiline strings such as help text?

comment:2 Changed 4 years ago by Jean-Paul Calderone

Let's try it out in howtos only for now and see how it goes.

For what it's worth, I'm more reluctant to apply this rule to any .py file where long lines are more likely to make life harder when actually writing and maintaining nearby software. The howto xhtml files don't suffer this issue, since they're already not primarily about writing Python.

comment:3 Changed 4 years ago by Jean-Paul Calderone

Description: modified (diff)

comment:4 Changed 4 years ago by Tom Prince

Author: tomprince
Branch: branches/sentence-per-line-6537

(In [39044]) Branching to sentence-per-line-6537.

comment:5 Changed 4 years ago by Tom Prince

Keywords: review added

I'm not sure how best to link to the blog (or whether that is even needed).

comment:6 Changed 4 years ago by Thijs Triemstra

Keywords: review removed
Owner: set to Tom Prince
  1. there's a typo in formatted on line 15
  2. same for reformated on line 29
  3. twisted will be around in 10 years but that blog(post) likely won't be.. I think you should either omit that url and include more of that 'fuller motivation' or leave that part out completely.

Thanks.

comment:7 Changed 4 years ago by Tom Prince

Keywords: review added
Owner: Tom Prince deleted

comment:8 Changed 4 years ago by Thijs Triemstra

Keywords: review removed
Owner: set to Tom Prince

Please merge.

comment:9 Changed 4 years ago by Tom Prince

Resolution: fixed
Status: newclosed

(In [40913]) Merge sentence-per-line-6537: Update coding-standard to reflect that documentation should be sentence per line.

Author: tom.prince Reviewers: thijs Fixes: #6537

This results in diffs that are easier to read, making documentation maintenance easier.

Note: See TracTickets for help on using tickets.