Opened 7 years ago

Closed 7 years ago

#6649 enhancement closed fixed (fixed)

mail.py should conform to docstring and whitespace standards

Reported by: Stacey Sern Owned by:
Priority: normal Milestone:
Component: mail Keywords: documentation
Cc: Branch: branches/mail-doc-6649
branch-diff, diff-cov, branch-cov, buildbot
Author: shira

Description

The docstrings in mail.py should be updated to provide descriptions of all classes, functions and methods as well as their parameters and attributes. The spacing before classes and functions should conform to the coding standards.

Change History (14)

comment:1 Changed 7 years ago by Stacey Sern

Author: shira
Branch: branches/mail-doc-6649

(In [39350]) Branching to 'mail-doc-6649'

comment:2 Changed 7 years ago by Stacey Sern

(In [39387]) Fix docstrings and whitespace.

refs #6649

comment:3 Changed 7 years ago by Stacey Sern

Keywords: documentation review added
Owner: Stacey Sern deleted

comment:4 Changed 7 years ago by Stacey Sern

(In [39395]) Fix formatting.

refs #6649

comment:5 Changed 7 years ago by Stacey Sern

(In [39406]) Modified IAliasableDomain.exists docstring.

refs #6649

comment:6 Changed 7 years ago by Stacey Sern

Keywords: review removed
Owner: set to Stacey Sern

comment:7 Changed 7 years ago by Stacey Sern

(In [39776]) Revised API documentation

refs #6649

comment:8 Changed 7 years ago by Stacey Sern

(In [39777]) Remove blank lines after class docstrings

refs #6649

comment:9 Changed 7 years ago by Stacey Sern

(In [39780]) Going back to original code after discovering twistedchecker problem

refs #6649

comment:10 Changed 7 years ago by Stacey Sern

Keywords: review added
Owner: Stacey Sern deleted

Revised to incorporate comments from other mail documentation code reviews and for general improvement in readability. Revisions include:

  • Changing type references from str to bytes
  • Using L{} instead of C{} for standard library types
  • Including a locally usable name in L{}
  • Removing blank lines after class docstrings
  • Removing (optional) in param descriptions
  • Changing the format of type descriptions of tuples
  • Changing the top file message

This builds with twistedchecker error 9016 on line 376 due to a bug in twistedchecker (bug report #1217379).

comment:11 Changed 7 years ago by lvh

Owner: set to lvh

comment:12 Changed 7 years ago by lvh

Keywords: review removed
Owner: lvh deleted

Hi shira,

Thanks for working on this. Documentation in crufty old bits of Twisted is often what turns people off from Twisted :)

  1. twisted/mail/mail.py L60: + if the name doesn't exists in this dictionary.
  2. twisted/mail/mail.py L98: + if the name doesn't exists in this dictionary.

Everything else looks good! Please merge after these two tidbits.

comment:13 Changed 7 years ago by Stacey Sern

(In [39898]) Fix typos noted in code review

refs #6649

comment:14 Changed 7 years ago by Stacey Sern

Resolution: fixed
Status: newclosed

(In [39923]) Merge mail-doc-6649: Fix docstrings and whitespace for mail.py

Author: shira Reviewer: lvh Fixes: #6649

Note: See TracTickets for help on using tickets.