docstring style for most functions and methods is obtuse

[Jean-Paul Calderone]

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.