Proper way to document keys in TypedDict?

What is the proper way to document keys inside a TypedDict? I don't see much information inside PEP 589 – TypedDict.

I can think of a few solutions:

1. Document keys inside a docstring (is there a standard field to use here?):

   class Foo(TypedDict):
       """
       I am a documented schema.
   
       Keys:
           key: This key has some implications needing documentation.
       """
   
       key: int
   

2. Document keys using inline comments inside the TypedDict

   class Foo(TypedDict):
       """I am a documented schema."""
   
       # This key has some implications needing documentation
       key: int
   

Is there an official approach to this? Anything specific that Sphinx may look for?

If we look at the class typing.TypedDict(dict) signature in the documentation we see it's a class, as the official docs start by saying:

TypedDict declares a dictionary type that expects all of its instances to have a certain set of keys

So documenting the TypedDict is straightforward because it also uses Class Definition Syntax each of the variables (meant to express key name and value type pairs) act as Class and Instance Variables.

When it's said in the question:

I can think of a few solutions:

1. Document keys inside a docstring
2. Document keys using inline comments inside the TypedDict

You can't use type comments with the usual # type: comment syntax in a TypedDict definition. Otherwise the usual two alternatives of putting a docstring above each variable declaration, or documenting the members in the class docstring are valid.

PEP 589 - Class-based Syntax

• The class body should only contain lines with item definitions of the form key: value_type, optionally preceded by a docstring. The syntax for item definitions is identical to attribute annotations, but there must be no initializer, and the key name actually refers to the string value of the key instead of an attribute name.

• Type comments cannot be used with the class-based syntax, for consistency with the class-based NamedTuple syntax. (Note that it would not be sufficient to support type comments for backwards compatibility with Python 2.7, since the class definition may have a total keyword argument, as discussed below, and this isn’t valid syntax in Python 2.7.) Instead, this PEP provides an alternative, assignment-based syntax for backwards compatibility, discussed in Alternative Syntax.

Last but not least:

1. (...) (is there a standard field to use here?)

Using Google style docstrings with the napoleon extension the docstring section of choice would be Attributes:. But if you want to be more precise you can create a custom section using napoleon_custom_sections (here's an example post). I tried looking around but I couldn't find a TypedDict documented in any public API. Since there's isn't an established convention you can use what you prefer. (If your documentation explicitly shows class inheritance it's implicit to the type what the Attributes: section will mean.)