Opened 15 years ago

Closed 14 years ago

#2567 defect closed fixed (fixed)

twisted.python.log.err does not have useful docstring

Reported by: konrads Owned by:
Priority: normal Milestone:
Component: core Keywords: log, documentation
Cc: Thijs Triemstra Branch: branches/err-docstring-2567
branch-diff, diff-cov, branch-cov, buildbot
Author: thijs

Description

twisted.python.log.err does not have useful docstring. It does not describe what arguments _stuff and more importantly _why are used for.

This is confusing.

Change History (12)

comment:1 Changed 14 years ago by Thijs Triemstra

Cc: Thijs Triemstra added
Keywords: documentation added
Owner: changed from Glyph to Thijs Triemstra
Status: newassigned

comment:2 Changed 14 years ago by Thijs Triemstra

Branch: branches/err-docstring-2657

comment:3 Changed 14 years ago by Thijs Triemstra

author: thijs
Branch: branches/err-docstring-2657branches/err-docstring-2567

(In [24536]) Branching to 'err-docstring-2567'

comment:4 Changed 14 years ago by Thijs Triemstra

Keywords: review added
Owner: Thijs Triemstra deleted
Status: assignednew

comment:5 Changed 14 years ago by Jean-Paul Calderone

Keywords: review removed
Owner: set to Thijs Triemstra

The text describing _stuff should just be part of the epytext markup for that parameter. Some more text for the _why parameter would probably be helpful as well.

comment:6 in reply to:  5 Changed 14 years ago by Thijs Triemstra

Keywords: review added
Owner: changed from Thijs Triemstra to Jean-Paul Calderone

Replying to exarkun:

The text describing _stuff should just be part of the epytext markup for that parameter. Some more text for the _why parameter would probably be helpful as well.

I moved the text in r24636, but leave the description for _why up to you since that is what the creator of this ticket asked for (but didnt provide), I'm just as confused as him ;)

comment:7 Changed 14 years ago by Jean-Paul Calderone

Owner: Jean-Paul Calderone deleted

I added r24650

comment:8 Changed 14 years ago by Glyph

Keywords: review removed
Owner: set to Jean-Paul Calderone

Looks good; but could _stuff get a @type as long as we're at it?

Do that and merge it.

comment:9 Changed 14 years ago by Thijs Triemstra

there's one None left that is missing the C{}

comment:10 Changed 14 years ago by Jean-Paul Calderone

(In [24658]) add @type for _stuff

refs #2567

comment:11 Changed 14 years ago by Jean-Paul Calderone

Resolution: fixed
Status: newclosed

(In [24659]) Merge err-docstring-2567

Author: thijs, exarkun Reviewer: glyph Fixes: #2567

Improve the docstring documentation of the parameters to twisted.python.log.err.

comment:12 Changed 11 years ago by <automation>

Owner: Jean-Paul Calderone deleted
Note: See TracTickets for help on using tickets.