Opened 15 months ago

Closed 9 months 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
(diff, github, buildbot, log)
Author: tomprince Launchpad Bug:

Description (last modified by exarkun)

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

Change History (9)

comment:1 Changed 15 months ago by tom.prince

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

comment:2 Changed 15 months 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 15 months ago by exarkun

  • Description modified (diff)

comment:4 Changed 14 months 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 14 months 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 14 months 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 14 months ago by tom.prince

  • Keywords review added
  • Owner tom.prince deleted

comment:8 Changed 13 months ago by thijs

  • Keywords review removed
  • Owner set to tom.prince

Please merge.

comment:9 Changed 9 months 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.