classification
Title: Make the docs for NotImplemented & NotImplementedError unambiguous
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: abarry, docs@python, ethan.furman, ezio.melotti, gvanrossum, martin.panter, python-dev, rhettinger
Priority: normal Keywords: patch

Created on 2016-06-06 18:59 by abarry, last changed 2016-08-05 22:10 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
NotImplemented_wording_1.patch abarry, 2016-06-06 18:59 review
NotImplemented_exceptions_wording_2.patch abarry, 2016-06-07 04:35 review
NotImplemented_exceptions_wording_3.patch abarry, 2016-06-07 05:15 review
NotImplemented_exceptions_wording_4.patch abarry, 2016-06-07 18:52 review
NotImplemented_exceptions_wording_5.patch abarry, 2016-07-06 21:51 review
issue27242.stoneleaf.01.patch ethan.furman, 2016-08-02 16:40 review
Messages (15)
msg267543 - (view) Author: Anilyka Barry (abarry) * (Python triager) Date: 2016-06-06 18:59
The NotImplemented docs aren't explicit enough when it comes to where it can/should be used. Patch attached.
msg267567 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2016-06-06 22:22
LGTM
msg267568 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-06-06 22:44
It would be nice to also clarify and differentiate NotImplementedError as well.
msg267588 - (view) Author: Anilyka Barry (abarry) * (Python triager) Date: 2016-06-07 04:35
Added further notes to `NotImplemented` and `NotImplementedError` to clearly state the differences between the two. I also added some more details to `TypeError` - I'm amazed at how little was described for such a common exception!

Maybe I explained a bit too thoroughly in some parts, but I like to have everything unambigous and well explained.

I haven't yet spent the time to learn how to build documentation (Soon™), so I'm going off the existing docs, and I try to follow the style as closely as possible.
msg267593 - (view) Author: Anilyka Barry (abarry) * (Python triager) Date: 2016-06-07 05:15
New patch with small tweaks. Thanks Jelle for the comments!
msg267724 - (view) Author: Anilyka Barry (abarry) * (Python triager) Date: 2016-06-07 18:52
More tweaks after Ethan's comments. This is starting to get way outside of the realm of NotImplemented, but it still makes for a good reference to point confused users at.
msg267776 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-06-08 04:38
Emanuel, have you seen <https://docs.python.org/devguide/documenting.html#building-the-documentation>? From my experience, install Sphinx, and then “make -C Doc/ html”.

About the patch, I think the “.. note” boxes should be intended under the NotImplementedError heading. The current box looks wrong sandwiched between NotImplemnted and Ellipsis.

(Personally I think “Note” boxes are an annoying distraction anyway, and should normally be written into the surrounding text. In this case “Note that” inside a “Note” box seems doubly redundant. But other people seem to like them, so I try to resist complaining :)
msg267843 - (view) Author: Anilyka Barry (abarry) * (Python triager) Date: 2016-06-08 12:59
Martin: yes, I plan to install Sphinx soon enough, so that I can build the docs.

As for the notes part, I indented it exactly like it was indented for other existing notes boxes in the same file. I'll change that if needed though.
msg267851 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-06-08 13:44
I think the box about NotImplementedError needs indenting too. See the box for <https://docs.python.org/3.5/library/functions.html#locals> for a better example.
msg269911 - (view) Author: Anilyka Barry (abarry) * (Python triager) Date: 2016-07-06 21:51
New patch with proper indenting, should be good as far as formatting is concerned :)
msg271825 - (view) Author: Anilyka Barry (abarry) * (Python triager) Date: 2016-08-02 14:10
Obligatory monthly ping.
msg271831 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2016-08-02 16:40
Did a little rewording and trimming (and formatting).  Tried to keep the ideas while not being so verbose.
msg271832 - (view) Author: Anilyka Barry (abarry) * (Python triager) Date: 2016-08-02 17:00
Thanks Ethan for the improved patch! Pointed out a typo and some nits, but other than that it's mostly good. I'm not that good at brevity, and I think your patch is much better on that regard :)
msg271833 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2016-08-02 17:19
Fixed the typos (thanks!), removed the self-reference, and went with "similar names and purposes".
msg272065 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-08-05 22:10
New changeset 142f5325af06 by Ethan Furman in branch 'default':
Clarify NotImplemented vs NotImplementedError.  Initial patch by Emmanuel Barry.  Closes issue 27242.
https://hg.python.org/cpython/rev/142f5325af06
History
Date User Action Args
2016-08-05 22:10:34python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg272065

resolution: fixed
stage: patch review -> resolved
2016-08-02 17:19:37ethan.furmansetmessages: + msg271833
2016-08-02 17:00:25abarrysetmessages: + msg271832
2016-08-02 16:42:23ezio.melottisetnosy: + ezio.melotti
2016-08-02 16:40:11ethan.furmansetfiles: + issue27242.stoneleaf.01.patch

messages: + msg271831
2016-08-02 14:10:07abarrysetmessages: + msg271825
2016-07-06 21:51:19abarrysetfiles: + NotImplemented_exceptions_wording_5.patch

messages: + msg269911
2016-06-08 17:37:29rhettingersettitle: Make the docs for NotImplemented & NotImplementedError unambigous -> Make the docs for NotImplemented & NotImplementedError unambiguous
2016-06-08 13:44:51martin.pantersetmessages: + msg267851
2016-06-08 12:59:56abarrysetmessages: + msg267843
2016-06-08 04:38:01martin.pantersetnosy: + martin.panter
messages: + msg267776
2016-06-07 18:52:40abarrysetfiles: + NotImplemented_exceptions_wording_4.patch

messages: + msg267724
2016-06-07 05:15:45abarrysetfiles: + NotImplemented_exceptions_wording_3.patch

messages: + msg267593
2016-06-07 04:35:34abarrysetfiles: + NotImplemented_exceptions_wording_2.patch

messages: + msg267588
title: Clarify the use cases of NotImplemented in the docs -> Make the docs for NotImplemented & NotImplementedError unambigous
2016-06-06 22:44:37rhettingersetnosy: + rhettinger
messages: + msg267568
2016-06-06 22:31:53ethan.furmansetnosy: + ethan.furman
2016-06-06 22:22:24gvanrossumsetnosy: + gvanrossum
messages: + msg267567
2016-06-06 18:59:27abarrycreate