Opened 4 years ago

Closed 3 years ago

#5055 defect closed fixed (fixed)

Typo in the strports docstring

Reported by: nkvoll Owned by: thijs
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: thijs, jesstess Branch:
Author: Launchpad Bug:

Description (last modified by thijs)

http://twistedmatrix.com/documents/current/api/twisted.application.strports.html#service

Currently it says:

    default	Do not use this parameter. It is deprecated since Twisted

    0.

Attachments (2)

mypatch.patch (513 bytes) - added by gdeng 3 years ago.
strportspatch.patch (629 bytes) - added by gdeng 3 years ago.

Download all attachments as: .zip

Change History (11)

comment:1 Changed 3 years ago by thijs

  • Cc thijs added
  • Description modified (diff)
  • Type changed from enhancement to defect

This looks like an issue with pydoctor or something to me..

comment:2 Changed 3 years ago by jesstess

  • Owner set to jesstess

comment:3 Changed 3 years ago by jesstess

  • Cc jesstess added

This is an epydoc bug; the "10.2.0." on a line by itself is matching on a regex for if something is a bullet. I've opened https://sourceforge.net/tracker/?func=detail&aid=3503223&group_id=32455&atid=405618 for this issue.

Here's the minimal reproducer from the epydoc ticket:

from epydoc.markup import epytext

docstring = """                                                                                                                                                                                                  
    Return the service corresponding to a description.                                                                                                                                                           
                                                                                                                                                                                                                 
    @param default: Do not use this parameter.  It is deprecated since Twisted                                                                                                                                   
        10.2.0.                                                                                                                                                                                                  
"""
print epytext.parse_docstring(docstring, [])

which produces

<epytext><para>Return the service corresponding to a description.</para><fieldlist><field><tag>param</tag><arg>default</arg><para inline=True>Do not use this parameter.  It is deprecated since Twisted</para><olist start='0'><li bullet='10.2.0.'></li></olist></field></fieldlist></epytext>

epydoc doesn't seem to be maintained anymore, so if I don't hear back on the ticket soon the easiest thing to do here is to tweak the line a bit to not match the buggy regex.

comment:4 Changed 3 years ago by gdeng

  • Owner changed from jesstess to gdeng

Changed 3 years ago by gdeng

comment:5 Changed 3 years ago by gdeng

  • Keywords review added
  • Owner gdeng deleted

comment:6 Changed 3 years ago by itamar

  • Keywords review removed
  • Owner set to gdeng

Thanks for the patch! There are a couple of minor problems:

  1. While that does look like it would solve the problem, it also violates our coding standard line length limit (http://twistedmatrix.com/documents/current/core/development/policy/coding-standard.html#auto5); maybe keep the lines wrapped, but rephrase the sentence somehow so "10.2.0" isn't the last thing on the line?
  2. Patches should include news files, as documented here - http://twistedmatrix.com/trac/wiki/ReviewProcess#Newsfiles - in this case you'd want an empty .misc file since it's a trivial change. If you svn add the news file it will show up in svn diff output.

Please add a new patch and re-add the review keyword and we can get this merged.

Changed 3 years ago by gdeng

comment:7 Changed 3 years ago by gdeng

  • Keywords review added
  • Owner gdeng deleted

comment:8 Changed 3 years ago by thijs

  • Keywords documentation added; review removed
  • Owner set to thijs
  • Status changed from new to assigned

Thanks I will apply the patch.

comment:9 Changed 3 years ago by thijs

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

(In [34127]) Apply strportspatch.patch: Correct formatting in the docstring of t.application.strports.service.

Author: gdeng
Reviewer: jesstess, itamar, thijs
Fixes: #5055

Note: See TracTickets for help on using tickets.