Confused about docs

[oxinabox]

Eh, I'm finding it very hard to work out what methods are implemented for what in what release thanks to all this churn.

Pkg finds the current release at 0.18.15 for me, which uses dequeue! for PriorityQueue and does not implement popfirst! - at least, I am shouted at for trying to use it.

The documentation, however, merrily tells me that I should definitely use popfirst! , despite (again), this not being implemented in the release that Pkg thinks is most recent.

If this isn't implemented in an actually released version, can the documentation at least not claim this works when it doesn't yet?

Originally posted by @aoanla in https://github.com/JuliaCollections/DataStructures.jl/issues/845#issuecomment-1859153774

[oxinabox]

The stable docs don't seem to mention popfirst! at all: https://juliacollections.github.io/DataStructures.jl/stable/search/?q=popfirst%21

The dev docs do: https://juliacollections.github.io/DataStructures.jl/dev/search/?q=popfirst%21

The very purpose of the dev docs is to be the docs for the currently in dev (i.e. not released) version of the package.

You can change which version of the docs you are looking at with the menu selector one the side: (Which moves between versions of the docs as on the dev version we have been)

There is hardly any churn, this package is very slow moving, and hasn't released breaking changes in years. These changes are needful to get us to 1.0, where we are consistent with the names of all the functions in Base (https://github.com/JuliaCollections/DataStructures.jl/issues/479). Which is taking a long time, due to limited time people have to work on this.

[aoanla]

Hm, the actual problem is that neither 'stable' nor 'dev' are linked to by quite a lot of other places (including the top search engine hits) - they instead link to 'latest' (which, itself, silently picks 'dev' - presumably as it's the top of the list - but retains 'latest' in the URL )

https://juliacollections.github.io/DataStructures.jl/latest/

I assert that this is misleading - most people looking for the "latest" docs mean "latest stable" - and is made worse by the fact that the only way to tell what version "latest" has picked (and that it isn't a stable release) is to examine the version selector at the bottom right (which is hidden by default on mobile, for example).

This is fairly poor UI - dev versions should at least have a 'This documentation is for a development release' style banner somewhere on the page, especially if 'latest' is going to silently select them.

On Mon, 18 Dec 2023, 06:51 Frames White, @.***> wrote:

The stable docs don't seem to mention popfirst! at all: https://juliacollections.github.io/DataStructures.jl/stable/search/?q=popfirst%21

The dev docs do: https://juliacollections.github.io/DataStructures.jl/dev/search/?q=popfirst%21

The very purpose of the dev docs is to be the docs for the currently in dev (i.e. not released) version of the package.

You can change which version of the docs you are looking at with the menu selector one the side: (Which moves between versions of the docs as on the dev version we have been) image.png (view on web) https://github.com/JuliaCollections/DataStructures.jl/assets/5127634/c086a4fe-1f57-45b9-afe8-307d9b5f84d3 image.png (view on web) https://github.com/JuliaCollections/DataStructures.jl/assets/5127634/5c0dbdf4-1e40-4666-a952-49c2fd1017aa

There is hardly any churn, this package is very slow moving, and hasn't released breaking changes in years. These changes are needful to get us to 1.0, where we are consistent with the names of all the functions in Base (#479 https://github.com/JuliaCollections/DataStructures.jl/issues/479). Which is taking a long time, due to limited time people have to work on this.

— Reply to this email directly, view it on GitHub https://github.com/JuliaCollections/DataStructures.jl/issues/885#issuecomment-1859650690, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABNRWLJDZFQZTLIPVVNDDZ3YJ7RVVAVCNFSM6AAAAABAZAUX56VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQNJZGY2TANRZGA . You are receiving this because you were mentioned.Message ID: @.***>

[oxinabox]

That's a good suggestion. I have opened a issue on Documenter.jl to see if we can get that feature added. https://github.com/JuliaDocs/Documenter.jl/issues/2382

We also should run the script linked in https://github.com/JuliaDocs/Documenter.jl/pull/1577 to make sure our outdated docs have the outdated banner.