Opened 6 years ago

Last modified 6 years ago

#6427 enhancement new

opt_* docstrings override options specified in optParameters in help output (in twisted.python.usage.Options subclasses)

Reported by: Tom Prince Owned by:
Priority: normal Milestone:
Component: core Keywords:
Cc: Branch:
Author:

Description

Since the coding standard says that everything needs a docstring, many opt_* functions have docstrings, but usually the description in optParameters is better as user visible documentation, if it is specified.

I'm not sure how best to address this. Some options:

  1. Change the coding standard to require no docstring for opt_* methods.
  2. Make optParameters text override opt_* docstrings.
  3. Require opt_* docstrings to be appropriate for display to the user.
    • This would either require them to not have epytext markup, or have that markup be stripped.

Change History (2)

comment:1 Changed 6 years ago by Jean-Paul Calderone

Option (2) sounds best to me. Option (1) and option (3) share the same drawback: an opt_* method should be explained to users and future maintainers just like any other method. They need docstrings as much as anything else does.

Actually, it's a mistake and a violation of the coding standard that opt_* method docstrings get used as user-facing documentation now, I think. According to the Docstrings section of the coding standard, "Docstrings are never to be used to provide semantic information about an object". I may be stretching the definition of "semantic information" slightly, but it does seem to me that using the docstring to define the human-facing explanation for an option runs afoul of this section.

comment:2 Changed 6 years ago by Jean-Paul Calderone

Substitution text doesn't need to be supplied by optParameters, of course. It could be kept in some other structure. And it's actually not required to have an entry in optParameters (or optFlags) when defining an opt_* method. So perhaps another option would be an attribute on the opt_* method. Or we could just say if you want to write the user-facing documentation for an option, you have to put it in optParameters or optFlags.

Note: See TracTickets for help on using tickets.