classification
Title: Suggested changes for https://docs.python.org/3.6/extending/extending.html
Type: behavior Stage:
Components: Documentation Versions: Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: ArthurGoldberg, docs@python, fdrake
Priority: normal Keywords:

Created on 2017-04-05 18:46 by ArthurGoldberg, last changed 2017-04-05 20:07 by fdrake.

Messages (2)
msg291192 - (view) Author: Arthur Goldberg (ArthurGoldberg) Date: 2017-04-05 18:46
I've just taught myself how to write C extensions to Python with https://docs.python.org/3.6/extending/extending.html. I think it's quite good.

Nevertheless, I've some suggested improvements. These all use the vi s/// replacement syntax.

Ambiguous 'it':
s/If the latter header file does not exist on your system, it declares the functions malloc(), free() and realloc() directly./If the latter header file does not exist on your system, Python.h declares the functions malloc(), free() and realloc() directly./

Unclear, as 'The C function' refers to the specific example, whereas 'always has' implies that this applies to all calls from Python to C:
s/The C function always has two arguments, conventionally/A C function called by Python always has two arguments, conventionally/

In 
PyMODINIT_FUNC
PyInit_spam(void)
{
    PyObject *m;

    m = PyModule_Create(&spammodule);
    if (m == NULL)
        return NULL;

    SpamError = PyErr_NewException("spam.error", NULL, NULL);
    Py_INCREF(SpamError);
    PyModule_AddObject(m, "error", SpamError);
    return m;
}

remove
    m = PyModule_Create(&spammodule);
    if (m == NULL)
        return NULL;
and replace it with
    
    ...
    
because it won't compile because spammodule has not been described yet on the page.

Self-contradictory: 'normally always' is an oxymoron. 
s/It should normally always be METH_VARARGS or METH_VARARGS | METH_KEYWORDS; a value of 0 means that an obsolete variant of PyArg_ParseTuple() is used./It should always be METH_VARARGS or METH_VARARGS | METH_KEYWORDS; however, legacy code may use 0, which indicates that an obsolete variant of PyArg_ParseTuple() is being used./

Incomplete: this comment doesn't contain a complete thought
s/module documentation, may be NULL/pointer to a string containing the module's documentation, or NULL if none is provided/

Provide hyperlink: for user convenience, add a hyperlink to 'Modules/xxmodule.c'
s/included in the Python source distribution as Modules/xxmodule.c/included in the Python source distribution as Modules/xxmodule.c/

Incomplete: It would be good to lead programmers towards the easiest approach. 
s/ If you use dynamic loading,/<new paragraph> If you can use dynamic loading, the the easiest approach is to use Python's distutils module to build your module. If you use dynamic loading,/
msg291193 - (view) Author: Arthur Goldberg (ArthurGoldberg) Date: 2017-04-05 19:52
Also, 

Incorrect number agreement:
s/strategy that minimizes this kind of errors/strategy that minimizes this kind of error/
History
Date User Action Args
2017-04-05 20:07:15fdrakesetnosy: + fdrake
2017-04-05 19:52:21ArthurGoldbergsetmessages: + msg291193
2017-04-05 18:46:35ArthurGoldbergcreate