Improve ImmutableDict doc #58360
Open
Improve ImmutableDict doc #58360
+27
−6
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
I had difficulty using the data structure based on the current version of the docs, so I gathered up what from experimentation, research on the Discourse site, and reading the code and wrote this.
Fix whitespace errors
Remove tab.
There was a problem hiding this comment.
Thanks for aggregating this and writing it up! It's good to have this documented.
This content is a little too tutorial style for a docstring, which is typically primarily for reference (i.e. concise, precise, and comprehensive specification of the behavior of an object). Perhaps you could put some of it in an "extended help" section (described here) to make the primary docstring a bit shorter.
| @@ -778,14 +778,35 @@ end | |||
| """ | |||
| ImmutableDict | |||
There was a problem hiding this comment.
Suggested change
| ImmutableDict | |
| Base.ImmutableDict |
Comment on lines
+784
to
+785
| search of a linked list. `ImmutableDict` is `public` rather than | ||
| `export`; to access it one must write `Base.ImmutableDict` |
There was a problem hiding this comment.
This can be conveyed by example by using Base.ImmutableDict in the opening line
Suggested change
| search of a linked list. `ImmutableDict` is `public` rather than | |
| `export`; to access it one must write `Base.ImmutableDict` | |
| search of a linked list. |
Comment on lines
+792
to
+793
| type of the dictionary elements; the returned value will be the head | ||
| of the list. To add to the dictionary use |
There was a problem hiding this comment.
What does "the head of the list" mean?
Comment on lines
+801
to
+802
| The types of elements may be specified; this is useful when keys or | ||
| values of `Union` or `Any` types are desired. |
There was a problem hiding this comment.
Suggested change
| The types of elements may be specified; this is useful when keys or | |
| values of `Union` or `Any` types are desired. | |
| The types of elements may be specified; this is useful when additional keys or values will be added that are not of the same type as the initial elements. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I had difficulty using the data structure based on the current version of the docs, so I gathered up what from experimentation, research on the Discourse site, and reading the code and wrote this.