More Dict and Set examples #33936
Fixes JuliaLang#33936 (comment) Fixes JuliaLang#33936 (comment) Fixes JuliaLang#33936 (comment) Fixes JuliaLang#33936 (comment) Set filtering/looping example Moving union, intersect, setdiff examples to docstrings Fixes JuliaLang#33936 (comment) AbstractSet fixes Fixes JuliaLang#33936 (comment) Fixes JuliaLang#33936 (comment) Fixes JuliaLang#33936 (comment) Fixes JuliaLang#33936 (comment) Fixes JuliaLang#33936 (comment) Fixes JuliaLang#33936 (comment) Fixes JuliaLang#33936 (comment) set.jl fixes Fixes JuliaLang#33936 (comment) Fixes JuliaLang#33936 (comment) Fixes JuliaLang#33936 (comment) Fix setdiff
General note about this PR:
As an example see these
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
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:
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.
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.
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.
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.