Skip to content

Conversation

erlend-aasland
Copy link
Contributor

@erlend-aasland erlend-aasland commented Feb 16, 2023

@erlend-aasland
Copy link
Contributor Author

  • I removed the duplicate example; it should be sufficient to provide a single example.
  • Use note:: to put emphasis on non-standard reference count semantics in the set function.
  • Mark the getter as returning a borrowed reference.
  • Apply Diátaxis: be succinct and to the point (and hopefully also clearer)
@CAM-Gerlach CAM-Gerlach added the docs Documentation in the Doc dir label Feb 17, 2023
Copy link
Member

@CAM-Gerlach CAM-Gerlach left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @erlend-aasland ; this is a substantial improvement to the previous docs.

Perhaps its worth fixing the other couple remaining similar docs defects also introduced in PR #101607 , namely in the descriptions of the newly documented functions PyException_GetArgs and PyException_SetArgs (that could use a similar (if much simpler) treatment as here), and the deprecation notices added to PyErr_Fetch, PyErr_Restore and PyErr_NormalizeException not being added to, and particularly duplicating, the .. deprecated directive.

@erlend-aasland
Copy link
Contributor Author

Thanks @erlend-aasland ; this is a substantial improvement to the previous docs.

Thanks, and thanks for the review!

Perhaps its worth fixing the other couple remaining similar docs defects also introduced in PR #101607 , namely in the descriptions of the newly documented functions PyException_GetArgs and PyException_SetArgs (that could use a similar (if much simpler) treatment as here), and the deprecation notices added to PyErr_Fetch, PyErr_Restore and PyErr_NormalizeException not being added to, and particularly duplicating, the .. deprecated directive.

Definitely; perhaps as a follow-up PR?

@CAM-Gerlach
Copy link
Member

Definitely; perhaps as a follow-up PR?

Yeah certainly could be; up to you, of course

Copy link
Member

@CAM-Gerlach CAM-Gerlach left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A couple followup suggestions

Copy link
Member

@CAM-Gerlach CAM-Gerlach left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM from me; thanks @erlend-aasland !

@erlend-aasland
Copy link
Contributor Author

Thanks for the review, CAM; highly appreciated. I'll wait for @iritkatriel's or @markshannon's approval before landing.

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
@erlend-aasland
Copy link
Contributor Author

Thanks for the reviews, Irit and CAM; highly appreciated. I'll create a follow-up PR Any Time Soon™.

@erlend-aasland erlend-aasland deleted the fixup-exc-docs branch February 19, 2023 20:22
erlend-aasland added a commit to erlend-aasland/cpython that referenced this pull request Feb 19, 2023
jaraco pushed a commit to jaraco/cpython that referenced this pull request Feb 20, 2023
…1962) Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
carljm added a commit to carljm/cpython that referenced this pull request Feb 20, 2023
* main: (60 commits) pythongh-102056: Fix a few bugs in error handling of exception printing code (python#102078) pythongh-102011: use sys.exception() instead of sys.exc_info() in docs where possible (python#102012) pythongh-101566: Sync with zipp 3.14. (pythonGH-102018) pythonGH-99818: improve the documentation for zipfile.Path and Traversable (pythonGH-101589) pythongh-88233: zipfile: handle extras after a zip64 extra (pythonGH-96161) pythongh-101981: Apply HOMEBREW related environment variables (pythongh-102074) pythongh-101907: Stop using `_Py_OPCODE` and `_Py_OPARG` macros (pythonGH-101912) pythongh-101819: Adapt _io types to heap types, batch 1 (pythonGH-101949) pythongh-101981: Build macOS as recommended by the devguide (pythonGH-102070) pythongh-97786: Fix compiler warnings in pytime.c (python#101826) pythongh-101578: Amend PyErr_{Set,Get}RaisedException docs (python#101962) Misc improvements to the float tutorial (pythonGH-102052) pythongh-85417: Clarify behaviour on branch cuts in cmath module (python#102046) pythongh-100425: Update tutorial docs related to sum() accuracy (FH-101854) Add missing 'is' to `cmath.log()` docstring (python#102049) pythongh-100210: Correct the comment link for unescaping HTML (python#100212) pythongh-97930: Also include subdirectory in makefile. (python#102030) pythongh-99735: Use required=True in argparse subparsers example (python#100927) Fix incorrectly documented attribute in csv docs (python#101250) pythonGH-84783: Make the slice object hashable (pythonGH-101264) ...
carljm added a commit to carljm/cpython that referenced this pull request Feb 22, 2023
* main: (225 commits) pythongh-102056: Fix a few bugs in error handling of exception printing code (python#102078) pythongh-102011: use sys.exception() instead of sys.exc_info() in docs where possible (python#102012) pythongh-101566: Sync with zipp 3.14. (pythonGH-102018) pythonGH-99818: improve the documentation for zipfile.Path and Traversable (pythonGH-101589) pythongh-88233: zipfile: handle extras after a zip64 extra (pythonGH-96161) pythongh-101981: Apply HOMEBREW related environment variables (pythongh-102074) pythongh-101907: Stop using `_Py_OPCODE` and `_Py_OPARG` macros (pythonGH-101912) pythongh-101819: Adapt _io types to heap types, batch 1 (pythonGH-101949) pythongh-101981: Build macOS as recommended by the devguide (pythonGH-102070) pythongh-97786: Fix compiler warnings in pytime.c (python#101826) pythongh-101578: Amend PyErr_{Set,Get}RaisedException docs (python#101962) Misc improvements to the float tutorial (pythonGH-102052) pythongh-85417: Clarify behaviour on branch cuts in cmath module (python#102046) pythongh-100425: Update tutorial docs related to sum() accuracy (FH-101854) Add missing 'is' to `cmath.log()` docstring (python#102049) pythongh-100210: Correct the comment link for unescaping HTML (python#100212) pythongh-97930: Also include subdirectory in makefile. (python#102030) pythongh-99735: Use required=True in argparse subparsers example (python#100927) Fix incorrectly documented attribute in csv docs (python#101250) pythonGH-84783: Make the slice object hashable (pythonGH-101264) ...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation in the Doc dir skip news

4 participants