docstring style for most functions and methods is obtuse
Bug #312787 reported by
Jean-Paul Calderone
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.