[docs] [issue17589] Make documentation about macros in C API explicit about rvalue vs statement

[Larry Hastings]

New submission from Larry Hastings:

CPython API "functions" implemented as macros can expand into either
rvalues or statements.  Most expand into statements (often using the
do {} while (0) syntactic sugar trick), but occasionally they're legal
as rvalues.

As of this writing Py_INCREF works as an rvalue.  But discussion on
another tracker issue (#17206) proposes changing the implementation
in such a way that it will only be usable as a statement.  Although
it's mildly unlikely, it's certainly possible that this will break
somebody's code.

I propose that the documentation make an explicit ruling on whether
macros are usable as rvalues or as statements.  Perhaps a blanket
statement would suffice, "all macros are only supported for use as
statements except where explicitly noted", then annotate specific
macros that are supported for use as rvalues.  Though that raises the
question of acknowledging in the documentation that some things are
macros--I think the documentation glosses over that fact right now.

Note: I added you three (Georg, Mark, Martin) as I thought you might
have an opinion on this one way or the other.  If you're not interested,
my apologies.

----------
assignee: docs at python
components: Documentation
messages: 185646
nosy: Mark.Shannon, docs at python, georg.brandl, larry, loewis
priority: normal
severity: normal
stage: needs patch
status: open
title: Make documentation about  macros in C API explicit about rvalue vs statement
type: enhancement
versions: Python 3.4

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue17589>
_______________________________________