Opened 2 years ago

Closed 18 months ago

#5918 enhancement closed fixed (fixed)

t.p.b.StatefulStringProtocol has undocumented .state instance attribute

Reported by: devinj Owned by: thijs
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: thijs Branch: branches/state-doc-5918
(diff, github, buildbot, log)
Author: thijs Launchpad Bug:

Description

http://twistedmatrix.com/trac/browser/tags/releases/twisted-12.1.0/twisted/protocols/basic.py#L846

http://twistedmatrix.com/documents/current/api/twisted.protocols.basic.StatefulStringProtocol.html

I'm not sure that instance attributes are universally supposed to be documented, but the attribute name "state" is useful enough for others (and nonobvious enough in subclasses, e.g. AMP) that maybe it should be documented. I ran into this problem last year when I used state as an instance attribute for a subclass, and found it very confusing. (At the time, I forgot to report the missing documentation, sorry.)

Change History (6)

comment:1 Changed 2 years ago by thijs

  • Cc thijs added
  • Keywords documentation added

comment:2 Changed 19 months ago by thijs

  • Author set to thijs
  • Branch set to branches/state-doc-5918

(In [37212]) Branching to 'state-doc-5918'

comment:3 Changed 19 months ago by thijs

(In [37213]) document state attr, add news file. refs #5918

comment:4 Changed 19 months ago by thijs

  • Keywords review added

Added documentation and forced a build. Up for review.

comment:5 Changed 19 months ago by tom.prince

  • Keywords review removed
  • Owner set to thijs

Looks good. Please commit.

comment:6 Changed 18 months ago by thijs

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

(In [37248]) Merge state-doc-5918: Documented the state attribute of StatefulStringProtocol.

Author: thijs
Reviewer: tom.prince
Fixes: #5918

Note: See TracTickets for help on using tickets.