JuliaCollections
Improved Queue and Stack Documentation + docstrings
Following #800. Note that this PR splits Queue and Stack documentation pages into two separate pages.
Sorry for taking so long..
Thanks for the comments! I see the merit of keeping the docstrings succinct (as it seems to be the trend around most of Julia packages), but in this case I've decided to be a little more verbose and add docstring examples for each of the exported functions (except for the iterators which have their own example at the beginning of the stack.md doc file). Ideally, for 1.0, I believe we should have at least one example for each exported function regardless of how trivial they may look.
Let me know what you think about these examples! So far I only added them to the Stack type, with your feedback I can make the requested changes and do the same for the Queue.
I am neural on most of the examples.
Low key against them for ones that I don't think we should have method docstrings for in the first place (because of the method already being well described by the overall function documentation).
But i do see the utility of showing examples for first and last for Queue and Stack
I do think if we want to keep them it is possibly worth hiding them behind ## Extended Help
For long docstrings, consider splitting the documentation with an # Extended help header. The typical help-mode will show only the material above the header; you can access the full help by adding a '?' at the beginning of the expression (i.e., "??foo" rather than "?foo").
(https://docs.julialang.org/en/v1/manual/documentation/)
All in all this is looking really nice. Clear improvement over status quo
I've trimmed most of the code examples leaving only first, last (as you suggested) and I also took liberty of leaving the examples of ==; it occurred to me that the previous example and docstrings for that method were not precise enough. Besides that, I also made a couple of minor changes in the docstrings in general of Stack, see how that reads to you.