search

pyglet / pyglet

pyglet is a cross-platform windowing and multimedia library for Python, for developing games and other visually rich applications.
http://pyglet.org
BSD 3-Clause "New" or "Revised" License
1.78k stars 294 forks source link

Doc and typing improvements for pyglet.libs.darwin #1108

Closed pushfoo closed 2 weeks ago

pushfoo commented 2 weeks ago

TL;DR:

  1. I had less free time & access to real-world test hardware than expected
  2. It seems worth PRing now because:
    • arcane code first written in 2011 is now legible
    • I don't want to block people
  3. This still hasn't been tested on real hardware yet

Current changes

(1/4) Turn prior feedback from @caffeinepills into committed code

I've included some older Disocrd feedback by:

  1. Explaining the doc situation for pyglet.lib:
    • These modules don't get web doc built
    • Docstrings should favor immediate human readability
  2. Removing hard-to-read Sphinx formatting from my previous drafts
  3. Removing overly clever attempts to type annotate ctypes items

(2/4) Partly document and annotate pyglet.libs.darwin.cocoapy.runtime

TL;DR: Doc, annotations, and signature upgrade make some code legible

  1. Added docstrings and comments with links to Apple documentation
  2. Annotated some signatures in pyglet.libs.darwin.runtime
  3. Backward-compatible changes to send_message:
    • Decipher near-hieroglyphic signature
    • Match the Python doc's variadic function call specification by allowing arbitrary sequences for argtypes
    • Use type-annotated keyword arguments with defaults instead of kwargs.get
    • Limited use of TypeVar for the result response type

mypy isn't perfectly happy, but that seems okay. It's unhappy with other things too.

(3/4) Comments, annotations, and a bonus Exception type for coreaudio.py

  1. Add cross-references to apple doc
  2. Add annotations and docstrings
  3. Reorder some constants for clarity
  4. Cleaner spacing
  5. Bonus: Add CoreAudioException
    • We have very vague exceptions
    • We should fix that
    • This is a step towards it, but I can revert it for now if you'd like

(4/4) Quartzkeys doc

Mostly just organization and aesthetics