More Dict and Set examples

[aminya]

Ready to get merged...

[jonas-schulze]

The way you print the sets might be incompatible with #33300.

[aminya]

The way you print the sets might be incompatible with #33300.

I should check with nightly then.

[jonas-schulze]

I like the additional examples. 🙂

I just noticed that your examples for sets are no jldoctests. If that is intentional (as to not rely on a particular order of the elements when printing; there might even be another issue/PR for that) I think that's fine.

[aminya]

This is ready to get merged.

[KristofferC]

This is ready to get merged.

Seems like all CI failed though.

[KristofferC]

This still just seems like a rewrite of the section above the example above this. I think it can be removed.

[aminya]

The section above doesn't talk about the difference between d[x] and get()

[KristofferC]

I feel like this whole paragraph can be removed. This is mostly rehashing things that have already been mentioned.

[aminya]

Here I am describing in the context of push!.

[KristofferC]

This seems like a restatment of the first part of this docstring:

Given a single iterable argument, constructs a Dict whose key-value pairs
are taken from 2-tuples (key,value) generated by the argument.

[aminya]

No, it is not. Dict(x => x^2 for x = 0:1:4) is different from Dict([x => x^2 for x = 0:1:4])

[aminya]

Also, now that I am thinking, the place of the 1st and 2nd examples should be changed. The 2nd example is 2X faster since it directly makes the Dict.

Examples

julia> Dict([("A", 1), ("B", 2)])
Dict{String,Int64} with 2 entries:
  "B" => 2
  "A" => 1

Alternatively, a sequence of pair arguments may be passed.

julia> d = Dict("A"=>1, "B"=>2)
Dict{String,Int64} with 2 entries:
  "B" => 2
  "A" => 1

[KristofferC]

This is the doctstring for the constructor Dict(). Now we are talking about modyfing an existing dict which feels out of scope for this docstring.

[aminya]

This is in the Extended help section of Dict. Dict doesn't have a manual like Array does, so this docstring is the best place for talking about modifying a Dict or etc.

[aminya]

General note about this PR:
This is a documentation for those who are not familiar with Julia, and may not infer all the features and capabilities from a single sentence. So having more description and example doesn't harm the user, but instead gives more knowledge.

As an example see these

• Matlab documentation for Container.map
  https://www.mathworks.com/help/matlab/ref/containers.map.html
• Python documentation for Dictionaries:
  https://docs.python.org/3/tutorial/datastructures.html#dictionaries

They all describe the ins and outs of the syntax plus having many different examples for different situations.

This PR is meant to fill the gap that exist for Julia for Dict and Set

[c42f]

Looking at the history of this PR, the discussion here has been very long for what I'd naively expect should be a simple change. Personally I glanced over these changes a few weeks ago and I had a feeling they "somehow didn't fit in", but couldn't express why.

However I was just thinking about the discussion at the end of #34226 and when I thought again of this issue it became clear what the problem is: @aminya is trying to write Tutorial documentation — in the sense of https://www.divio.com/blog/documentation (this is a must-read for anyone interested in good documentation) — but the Julia documentation currently has no place for tutorials.

Currently we have:

• Reference documentation is contained in docstrings which are terse but complete. @aminya this is the reason you are seeing resistance for adding large amounts of examples to the docstrings. Docstrings are just not a good place for extended tutorial-like content.
• Explanation is contained in the main Julia user manual (there is some small amount of tutorial content mixed in but that generally doesn't fit well with the style). As explanation, the manual currently doesn't serve beginners well, because tutorial content doesn't fit in nicely.
• Tutorials and How-Tos do not have a natural home.

To resolve this in a good way I think we really need an explicit home for tutorial content in the manual which is separate from the docstrings and separate from the Explanation part of the manual. Combined with good cross linking between the sections I think we'll get the best outcome.

[aminya]

I tried to help to improve the documentation of Julia. But there is resistance for adding manual, extra information, examples, and things that are specifically useful for beginners (rehashing, redundant rewording, and all the other adjectives used in the comments). I had to argue with people even for one sentence. This like cold water on people's passion for contribution. It hurts to put time on something, go back and forth fixing stuff, and in the end getting the impression that "you know what? let's forget about it!"

Some of the changes are not even in the docstrings https://github.com/JuliaLang/julia/pull/33936/files#diff-e0b60ee9b69a6054f919078823363231. I think the vision towards documentation PRs should also change.

The last time that the doc project was touched was in 2017. This shows the status pretty much.
https://github.com/JuliaLang/julia/projects/8

Similar:
FluxML/Flux.jl#985
FluxML/Flux.jl#853

[StefanKarpinski]

The last time that the doc project was touched was in 2017. This shows the status pretty much.
https://github.com/JuliaLang/julia/projects/8

The only thing that shows is that we don't use the GitHub projects feature.

Doc improvements are very much appreciated and merged all the time without issue. In this case, a lot of feedback was given and you effectively rejected large amounts of it. If you won't accept feedback on a PR, then it may not get merged and the person who gave that feedback may get tired and go away.

I think the basic issue with this PR is that it adds a lot of content to doc strings, which are supposed to be fairly minimal reference-style explanations of how specific APIs work. A lot of the feedback which was rejected was pushing the changes in that direction. With a more robust support for short versus extended docstrings (see #34226), having more and longer examples might be fine, but as it is there's a tradeoff between being more "friendly" versus overwhelming people with too many examples and details.

If you were to separate this into the manual additions, which are less controversial, and some minimal doc string improvements, that PR could be merged quickly and the addition of lots of examples to doc strings could wait on the resolution of how to handle extended docs.

[ViralBShah]

May I suggest closing this one and opening separate smaller PRs? I have been looking at many old doc PRs and merging them. In many cases I am doing the suggested work by the reviewers myself, which takes me more time than it would have taken the author.

It's hard to figure out the right answer. The quality of reviews for even small PRs is incredibly good, that leads to higher quality documentation that will literally help everyone who reads it. However, I can also see how it can be difficult for a new contributor.