[PYTHON DOC-SIG] PyCAPI 1.00a2 (now 133 entries and an index)

[Skip Montanaro]

Fredrik,
   
I took a quick look at your second pass.  What's there looks fine.  It's
moving too fast for me to edit and send back to you for comments.  Here are
some observations.

    1. One of the most critical pieces of information to document is
    reference counting behavior of the various functions.  It's the most
    difficult thing for a programmer to get right.  For each function input
    and output I'd like to know if references are consumed or produced by
    the function, for instance.

    2. While it's easy to get at the old names from rename2.h, I think they
    should be deprecated, perhaps not even documented at this point other
    than to have a link from, say, newlongobject to PyLong_FromLong in a
    function index.

    3. I'd like the most commonly used stuff documented first.  In my
    limited experience that would be things like argument passing (PyArg*),
    sequence (PySequence*, PyList*, PyTuple*) and mapping (PyMapping*,
    PyDict*) Get/Set/Slice functions, and object creation. Every module
    function has to deal with one or more of those areas to some degree.
    Many of the other C API names appear much less frequently in common
    usage, and may even not be meant for general programmer use, but are
    just meant for communication between different parts of the run-time
    system.

    4. I still think LaTeX or TeXinfo would be better vehicles for the
    actual text processing than HTML.  For one thing, TeX and it's various
    spinoff macro packages already have good cross-reference and index
    features.  I believe tools like latex2html can take advantage of them to
    generate links and indexes in generated HTML.

    5. I'd like to see a more stratified top-level structure, something
    like:

	Introduction
	    Terminology
		Owned vs. borrowed references
		...

	Types
	    PyFloat_Type
	    ...
	    Type Checking
		PyCallable_Check
		...

	Data Items
	    Py_True
	    Py_False
	    Py_None
	    Exceptions
		PyExc_IndexError
		...
	    Builtin Objects
		PyFloatObject
		...
		Object Macros
		    PyObject_HEAD
		    ...

	Reference Counting
	    Py_INCREF
	    ...

	Functions
	    Abstract Interface
		Object Protocol
		    PyObject_HasAttrString
		    ...

	    Argument Passing
		PyArg_ParseTuple
		...

	    List Functions
		PyList_Append
		...

	    Mapping Functions
	    Numeric Functions
	    String Functions
	    ...

    I think your current document starts to flesh out the Functions section
    of the above outline.

Skip Montanaro     |   Musi-Cal: http://concerts.calendar.com/
skip@calendar.com  |   Conference Calendar: http://conferences.calendar.com/
(518)372-5583      |   Python: http://www.python.org/

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================