Source code links for JSON documentation

[louiscipher]

BPO	15063
Nosy	@rhettinger, @orsenthil, @ezio-melotti, @merwok
Files	json_source_link.patch: patch file adding links to the documentation file json.rst

^{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 = <Date 2012-07-21.04:48:09.546>
created_at = <Date 2012-06-14.04:30:54.405>
labels = ['type-feature', 'docs']
title = 'Source code links for JSON documentation'
updated_at = <Date 2012-07-21.04:48:09.535>
user = 'https://bugs.python.org/louiscipher'

bugs.python.org fields:

activity = <Date 2012-07-21.04:48:09.535>
actor = 'orsenthil'
assignee = 'docs@python'
closed = True
closed_date = <Date 2012-07-21.04:48:09.546>
closer = 'orsenthil'
components = ['Documentation']
creation = <Date 2012-06-14.04:30:54.405>
creator = 'louiscipher'
dependencies = []
files = ['26006']
hgrepos = []
issue_num = 15063
keywords = ['patch']
message_count = 3.0
messages = ['162750', '162976', '165993']
nosy_count = 6.0
nosy_names = ['rhettinger', 'orsenthil', 'ezio.melotti', 'eric.araujo', 'docs@python', 'louiscipher']
pr_nums = []
priority = 'normal'
resolution = 'wont fix'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue15063'
versions = ['Python 2.7', 'Python 3.2', 'Python 3.3']

[louiscipher]

In some parts of the documentation there are links to the source code. While looking in the JSON documentation that link isn't there.

Not sure if this is wanted or if it's complete. But I'm submitting it anyway in the hopes of feedback.

[merwok]

The source links were added by Raymond for selected modules that he judged readable, well-written and useful companions to the documentation. For the json.encoder and decoder modules, I don’t think this is the case: the rst doc should explain well the behavior of the default encoder/decoder and how to subclass to change this behavior. Did you see something interesting in the code? I only had a look through it quickly, and saw the mix of C and Python code (which can be non-trivial to follow) and a dubious idiom (binding globals as locals to optimize access on CPython—doesn’t work on PyPy). My opinion is -1; what do other people think?

[orsenthil]

I am with Éric on this. Looking at json/decoder.py and json/encoder.py, I too feel that source link may not be helpful as much as it is helpful for others. Docs are best here. I am closing this report. Thanks!