Standardizing Docstrings to Align with PEP 257

[gsekulski]

This proposal is a follow-up to yesterday's IRC discussion, it suggests standardizing docstrings across the PyPy codebase to follow PEP 257.

Current State

Docstring formatting is inconsistent across the project. Some parts like pycompiler, main or reverse_debugging follow PEP 257, while others don't or do incorrectly. Observed issues include:

For one-line docstrings:

• Single string literal:
  Even though neither CPython nor PyPy cares; any string literal can become a docstring when it's the first thing inside a module/class/function. PEP recommends using triple quotes, as this makes it easier to expand later.
  

  pypy/pypy/interpreter/pyframe.py

  Lines 705 to 707 in c2324b8

  	def fget_f_lineno(self, space):
  	"Returns the line number of the instruction currently being executed."
  	if self.get_w_f_trace() is None:

• Incorrect formatting:
  One-line docstrings should not have blank lines before or after them.
  

  pypy/pypy/interpreter/pyframe.py

  Lines 675 to 679 in c2324b8

  	def init_cells(self):
  	"""
  	Initialize cellvars from self.locals_cells_stack_w.
  	"""
  	args_to_copy = self.pycode._args_as_cellvars

• Comment block used instead of a docstring:
  In some places one-line docstring should be used, not a comment block.
  

  pypy/pypy/interpreter/pyframe.py

  Lines 640 to 642 in c2324b8

  	def locals2fast(self):
  	# Copy values from self.w_locals to the fastlocals
  	w_locals = self.getorcreatedebug().w_locals

For multi-line docstrings:

• Missing summary line and inconsistent blank lines:
  Unless the entire docstring fits on a line, closing quotes should be on a line by themselves.
  

  pypy/pypy/interpreter/executioncontext.py

  Lines 399 to 403 in c2324b8

  	def checksignals(self):
  	"""Similar to PyErr_CheckSignals(). If called in the main thread,
  	and if signals are pending for the process, deliver them now
  	(i.e. call the signal handlers)."""
  	if self.space.check_signal_action is not None:

• Inconsistent formatting:
  Some files have varying formats for multi-line docstrings in the same section of code.
  

  pypy/pypy/interpreter/executioncontext.py

  Lines 427 to 433 in c2324b8

  	class AbstractActionFlag(object):
  	"""This holds in an integer the 'ticker'. If threads are enabled,
  	it is decremented at each bytecode; when it reaches zero, we release
  	the GIL. And whether we have threads or not, it is forced to zero
  	whenever we fire any of the asynchronous actions.
  	"""

  
  

  pypy/pypy/interpreter/executioncontext.py

  Lines 462 to 471 in c2324b8

  	def register_periodic_action(self, action, use_bytecode_counter):
  	"""
  	Register the PeriodicAsyncAction action to be called whenever the
  	tick counter becomes smaller than 0. If 'use_bytecode_counter' is
  	True, make sure that we decrease the tick counter at every bytecode.
  	This is needed for threads. Note that 'use_bytecode_counter' can be
  	False for signal handling, because whenever the process receives a
  	signal, the tick counter is set to -1 by C code in signals.h.
  	"""
  	assert isinstance(action, PeriodicAsyncAction)

Proposal

Refactor all docstrings to comply with PEP 257. One-line docstrings should follow PEP 257's one-line docstrign format, and multi-line docstrings should follow PEP 257's multi-line docstring format.
Django is a good model example. Adopting a similar consistency in PyPy could improve readability and ease of contribution.

Only the documentation would be modified—no functional changes.

Q

Please let me know if there would be interest in these changes. If so, I can prepare a pull request.

[mattip]

As mentioned in IRC: Fixing style for style sake is very unlikely to be accepted busy work. We have too many active branches for this to lead to anything but confusion and merge conflicts. It's better to improve code that you are touching for functionality/bug reasons. Thanks for the desire to help, but I will close this as a "won't fix".