Broken links in BTreeSet struct documentation

[alexcrichton]

There are broken links when looking at the BTreeSet structure. This happens because the structure can be viewed from two locations, both at varying depths of links so the relative links may or may not work:

• std::collections::BTreeSet - working
• std::collections::btree_set::BTreeSet - not working

[mitaa]

The same problem also causes the link [module-level documentation](index.html#insert-and-complex-keys) on the insert methods documentation on BTreeSet, BTreeMap and HashMap to sometimes refer to the wrong module (the immediate parent, instead of std::collections).

[phungleson]

@alexcrichton is there anything left to be done here, i can help the rest

[alexcrichton]

@phungleson if you can delete these lines and have this command work:

./x.py test src/tools/linkchecker

Then there's no more work to do! (other than deleting that block)

[phungleson]

Thanks @alexcrichton seems like I have to make some fixes

I got a lot of broken link after removing those lines lol

[phungleson]

While I am here, I wonder if I should format the docs here https://github.com/rust-lang/rust/blob/bae454edc5e18e81b831baf4a7647bf2dda620a8/src/libcollections/btree/map.rs to fit in 80 columns.

Currently it is quite hard to read properly.

[phungleson]

Sorry for my noob question, every time, I change something and run ./x.py test src/tools/linkchecker the whole rustc get re-complied again and it took at least 15' to 30' to run the thing.

I wonder if there is any less painful way to make changes and test in rust?

[steveklabnik]

Hm, that seems bad; I was recently doing this, and it didn't have to do a full recompile. Was more like 30 seconds each time. Wonder if you've hit a rustbuild bug?

…

On Sun, Feb 12, 2017 at 5:08 AM, Son ***@***.***> wrote: Sorry for my noop question, every time, I change something and run ./x.py test src/tools/linkchecker the whole rustc get re-complied again and it took at least 15' to 30' to run the thing. I wonder if there is any less painful way to make changes and test in rust? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#32130 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABsinv0I6rLR3llLhdo-u5RAd9QTwj2ks5rbtoFgaJpZM4HsJlf> .

[alexcrichton]

@phungleson you may want to pass --stage 0 as well, --stage 2 is the default and goes all the way to the end of the compiler.

Alternatively if you're just changing documentation then after you modify a file you can just use touch to move its mtime back in time.

[phungleson]

Hey thanks guys, --stage 0 is not super fast (5-10') but probably ok right now, have been looking into this for a while.

Wonder why struct.BTreeMap.html and similar files appear in 2 places? This is impossible to create correct relative links.

I think it is not fixed yet? and what is the correct place things should be?

Thanks

[alexcrichton]

Oh yeah I don't think this is fixed yet, hence the bug :)

[phungleson]

@alexcrichton which one should we keep, btree_map or btree/map and do you know where in the code that decides where the files should go?

I can dig a bit but might be faster if you know where it is.

Thanks!

[alexcrichton]

Nah unfortunately the details here are pretty out of cache for me :(

[MaloJaffre]

This problem also occurs in compiler docs (now built in #46278), where rustc_data_structures::sync::Lrc and rustc_data_structures::sync::RwLock are aliases to std types.

[ehuss]

Reopening until the exclusions in the link checker can be removed.

[jyn514]

Reopening until the exclusions in the link checker can be removed.

I wrote this in a commit message no one will read, so pasting here for visibility:

BTreeMap wants to link to the docs in std::collections, which are very detailed, and not alloc::collections, which is almost empty. But alloc is a dependency of std, so it's not possible to link to it across crates (#74481). What we could do instead is have the same documentation in both alloc::collections and std::collections, so that BTree can link to the alloc version. However the docs for collections in turn link to HashMap, which are only in std. So one way or another, some of the links will be broken.

(I suggested a while ago making HashMap available in alloc, but there wasn't a clear consensus on how to do that: https://rust-lang.zulipchat.com/#narrow/stream/219381-t-libs/topic/Why.20is.20HashMap.20in.20std.20and.20not.20alloc.3F)

[jyn514]

Triage: this is almost working, these are the last broken links left in the standard library:

rust/src/tools/linkchecker/main.rs

Lines 33 to 40 in 010c236

	const LINKCHECK_EXCEPTIONS: &[(&str, &[&str])] = &[
	// These try to link to std::collections, but are defined in alloc
	// https://github.com/rust-lang/rust/issues/74481
	("std/collections/btree_map/struct.BTreeMap.html", &["#insert-and-complex-keys"]),
	("std/collections/btree_set/struct.BTreeSet.html", &["#insert-and-complex-keys"]),
	("alloc/collections/btree_map/struct.BTreeMap.html", &["#insert-and-complex-keys"]),
	("alloc/collections/btree_set/struct.BTreeSet.html", &["#insert-and-complex-keys"]),
	];

[jyn514]

I'm going to mark this as a standard library bug; the rustdoc half of it is tracked at #74481.

[Dylan-DPC]

Closing this as the exclusions are tracked in #74481