The docstring of `dict()` should match the doc of `dict()` and it should be more understandable

[hyperkai]

The docstring of dict() doesn't match the doc of dict() and it isn't so understandable as shown below:

print(help(dict))
# class dict(object)
#  |  dict() -> new empty dictionary
#  |  dict(mapping) -> new dictionary initialized from a mapping object's
#  |      (key, value) pairs
#  |  dict(iterable) -> new dictionary initialized as if via:
#  |      d = {}
#  |      for k, v in iterable:
#  |          d[k] = v
#  |  dict(**kwargs) -> new dictionary initialized with the name=value pairs
#  |      in the keyword argument list.  For example:  dict(one=1, two=2)

So, it should be like below:

dict(**kwargs) -> E.g. dict(key1=value1, key2=value2)
dict(mapping, **kwargs) -> mapping is the dictionary made by mapping object
dict(iterable, **kwargs) -> iterable is e.g. [('key1', 'value1'), ('key2', 'value2')]) treated by {k:v for k, v in iterable}

[picnixz]

I think the docstring is clear enough. It gives sufficient examples.

[AA-Turner]

@hyperkai please avoid opening lots of new issues for related topics. In the last few months you've opened over 40 issues, the many of which maintainers have closed with no action needed.

Your suggestions and observations are valuable, but please combine these into fewer issues. For example the recent str/bytes/bytearray issues could have been in one meta-issue, or the recent few dict issues coudl have been in a single combined topic.

I would also suggest that you use a lower modality in your phrasing -- saying that "X should change" is instructive, and can be off-putting to the reader, especially when maintainers assess the issue and determine that no change is needed (as @picnixz suggests in this case).

A

[serhiy-storchaka]

This will be done as a side effect of #73536.