Opened 3 years ago

Closed 3 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 exarkun)

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

Change History (9)

comment:1 Changed 3 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 3 years ago by exarkun

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 3 years ago by exarkun

  • Description modified (diff)

comment:4 Changed 3 years ago by tomprince

  • Author set to tomprince
  • Branch set to branches/sentence-per-line-6537

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

comment:5 Changed 3 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 3 years ago by thijs

  • 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 3 years ago by tom.prince

  • Keywords review added
  • Owner tom.prince deleted

comment:8 Changed 3 years ago by thijs

  • Keywords review removed
  • Owner set to tom.prince

Please merge.

comment:9 Changed 3 years ago by tomprince

  • Resolution set to fixed
  • Status changed from new to closed

(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.