Document C docstring behavior for signature extraction

[jameshcorbett]

BPO	41430
Nosy	@jameshcorbett
PRs	gh-85602: Add docs for generating C function signatures #21673

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-07-29.00:00:19.531>
labels = ['type-feature', 'docs']
title = 'Document C docstring behavior'
updated_at = <Date 2020-07-29.01:25:49.742>
user = 'https://github.com/jameshcorbett'

bugs.python.org fields:

activity = <Date 2020-07-29.01:25:49.742>
actor = 'jameshcorbett'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-07-29.00:00:19.531>
creator = 'jameshcorbett'
dependencies = []
files = []
hgrepos = []
issue_num = 41430
keywords = ['patch']
message_count = 1.0
messages = ['374547']
nosy_count = 2.0
nosy_names = ['docs@python', 'jameshcorbett']
pr_nums = ['21673']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue41430'
versions = []

[jameshcorbett]

As described in https://stackoverflow.com/questions/25847035/what-are-signature-and-text-signature-used-for-in-python-3-4, https://bugs.python.org/issue20586, and https://stackoverflow.com/questions/50537407/add-a-signature-with-annotations-to-extension-methods, it is possible to embed a signature in docstrings for C functions, so that help and inspect.signature work properly on them. However, this functionality isn't documented anywhere. I think something should be added to the "extending and embedding the Python interpreter" tutorial.

[skirpichev]

I don't think we are ready to expose this stuff as public.

Recent discussion thread (with several PEP drafts): https://discuss.python.org/t/type-signatures-for-extension-modules-pep-draft/43914

Perhaps, most close issue to track the problem is capi-workgroup/problems#32. Maybe we should have some "feature"-type issue in the CPython repo, but this hardly is one.

I suggest close this as "not planned". It's not a documentation issue.

CC @picnixz

[picnixz]

I don't think we are ready to expose this stuff as public.

Ah! I thought we were ready! I never created a manual docstring for a function actually except using AC or something with slots. If we are not ready yet on our side, then I'm ok with closing it as "not planned" for now and re-open this one when we're ready to.

[skirpichev]

If we are not ready yet on our side

I think - no. Currently even annotations aren't supported (#81677). And no support for multiple signatures (#73536).

[picnixz]

When we'll be ready, then it will become a "docs" issue only. For now, we'll close it as not planned.