Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions Doc/library/stdtypes.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4755,11 +4755,12 @@ other sequence-like behavior.

There are currently two built-in set types, :class:`set` and :class:`frozenset`.
The :class:`set` type is mutable --- the contents can be changed using methods
like :meth:`~set.add` and :meth:`~set.remove`. Since it is mutable, it has no
hash value and cannot be used as either a dictionary key or as an element of
another set. The :class:`frozenset` type is immutable and :term:`hashable` ---
its contents cannot be altered after it is created; it can therefore be used as
a dictionary key or as an element of another set.
like :meth:`add <frozenset.add>` and :meth:`remove <frozenset.add>`.
Copy link
Member

Choose a reason for hiding this comment

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

There is no frozenset.add().

Copy link
Member Author

Choose a reason for hiding this comment

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

Because set and frozenset are documented together, there is no cross-reference target for set.add, it is labelled as frozenset.add instead. This link goes to the correct place.

Copy link
Member

Choose a reason for hiding this comment

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

But this is a wrong name for anchor. We should do something with this.

Copy link
Member Author

Choose a reason for hiding this comment

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

I agree. I plan to fix it, but it requires changes (& a release) of Sphinx. This PR makes the reference link to the right place, and more importantly means that no future reference errors can be introduced into stdtypes.rst.

Once it is fixed, I plan to go back and update here & a few other places where we have used a different target to the intended one.

Copy link
Member

Choose a reason for hiding this comment

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

Now, I think that we should reorganize the set/frozenset documentation in the way similar to the sequence or bytes/bytearray documentation.

  1. Dedent method descriptions and add class name prefixes. E.g.:
    .. method:: frozenset.isdisjoint(other, /)
                set.isdisjoint(other, /)
  2. Move operators to separate tables. This may wait.

Copy link
Member

Choose a reason for hiding this comment

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

#141857 implements this approach.

Copy link
Member

Choose a reason for hiding this comment

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

Wrong reverence to remove().

Since it is mutable, it has no hash value and cannot be used as
either a dictionary key or as an element of another set.
The :class:`frozenset` type is immutable and :term:`hashable` ---
its contents cannot be altered after it is created;
it can therefore be used as a dictionary key or as an element of another set.

Non-empty sets (not frozensets) can be created by placing a comma-separated list
of elements within braces, for example: ``{'jack', 'sjoerd'}``, in addition to the
Expand Down
1 change: 0 additions & 1 deletion Doc/tools/.nitignore
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@ Doc/library/pyexpat.rst
Doc/library/select.rst
Doc/library/socket.rst
Doc/library/ssl.rst
Doc/library/stdtypes.rst
Doc/library/termios.rst
Doc/library/test.rst
Doc/library/tkinter.rst
Expand Down
Loading