docstring style for most functions and methods is obtuse

Bug #312787 reported by Jean-Paul Calderone on 2008-12-31
2
Affects Status Importance Assigned to Milestone
pyOpenSSL
Fix Released
Medium
Unassigned

Bug Description

Most docstrings in pyOpenSSL are of this form:

  Returns the critical field of the X509Extension

  Arguments: self - The X509Extension object\n\
             args - The argument tuple, should be empty\n\
  Returns: The critical field.

This is bad. It's targeted at a C programmer reading the C implementation of the APIs. Instead, it should be targeted at a Python programmer trying to use the Python API. Maintainer notes for C programmers can go into comments, if necessary. This docstring conveys only useful information about the return value. The rest of the information should be dropped.

Changed in pyopenssl:
importance: Undecided → Medium
milestone: none → 0.10
status: New → Confirmed
Changed in pyopenssl:
status: Confirmed → Fix Committed
Changed in pyopenssl:
status: Fix Committed → Fix Released
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers