Opened 8 years ago

#6777 enhancement new

Document how to document that argument values should be a Constant

Reported by: lvh Owned by:
Priority: normal Milestone:
Component: core Keywords: documentation easy
Cc: Branch:
Author:

Description

It became obvious in #3926 during review (see https://twistedmatrix.com/trac/ticket/3926?replyto=70#comment:70) that there's no existing guideline that says how to document argument types when the argument type is one of the values of a twisted.python.constants.* subclass.

Concretely, I spelled one of these:

@type dataMode: One of L{GPGLLGPRMCFixQualities}.

tomprince suggested:

@type dataMode: L{GPGLLGPRMCFixQualities}

The purpose of this ticket is to create that guideline.

tomprince's suggestion is certainly terser, and arguably unambiguous (technically it's asking for instances of, but I don't think anyone would seriously do that). My suggestion trips my English parser up less.

Change History (0)

Note: See TracTickets for help on using tickets.