Display all platform-specific documentation on docs.rs #3076

madsmtm · 2023-09-01T10:44:28Z

This required a bit of refactoring regarding platform privacy, but all of it for the better.

Added an entry to CHANGELOG.md if knowledge of this change could be valuable to users

madsmtm · 2023-09-01T10:45:47Z

CHANGELOG.md

@@ -8,6 +8,7 @@ And please only add new entries to the top of this list, right below the `# Unre

 # Unreleased

+- **Breaking:** No longer export `platform::x11::XNotSupported`.


@notgull I couldn't see a reason why this was exported, so I removed it, but maybe you can shed some light on it?

daxpedda

I feel like this could become annoying to maintain, but generally a really good change for users!

src/lib.rs

kchibisov · 2023-09-03T21:39:09Z

I don't quite get the motivation behind this, it could be really confusing to show it all the time, given that you should pay attention to metadata, like where the function actually works.

I guess the only argument pro this is that it's easier to find docs for other targets, but I'd expect when you work with cross platform code you open docs for the target you want, since while winit can do such a thing with doc most stuff in projects doesn't have docs and internal stuff is obviously missed from the docs.

madsmtm · 2023-09-03T21:55:24Z

Motivation

You get to see immediately what functionality is available, without having to select on docs.rs the platform you're currently working on.

This would probably have gone a long way towards the user here finding a solution for their problem quicker.

The way the platform module looks on docs.rs now:

After this change:

kchibisov · 2023-09-03T22:00:12Z

I mean, if they do cross dev, they should open docs with the correct target in the end. I'm just afraid to maintain that and work with such docs because I'm sort of really used to how it works based on target and I use the docs based on target.

The docs.rs even has a field to show docs per target, which sort of implies that they work for this target, but if we always show all the docs you can't really rely on your target picking.

Like for example I don't even want to see docs for macOS when writing code for linux, like why would I even have to read them and in my search, if they are just irrelevant for me?

madsmtm · 2023-09-03T22:37:13Z

Hmm, I definitely get your points! I think the best answer to that would be that the rustdoc team has implemented this feature because it's useful for users. I actually thought I could find a lot of examples of this, but it's quite hard since a lot of Rust code is cross-platform. (I also found examples of crates that don't do this, so take it with a grain of salt). But at least two examples:

std::os
tokio::net (and the rest of tokio)

Myself, I've often wished libc did this, I find it really difficult to know the exhaustive list of platforms e.g. libc::pthread_main_np is available on.

(If you're developing locally, you could always just do cargo doc --open, at least for now it'll only show docs for your own target/feature combinations. It's in any case always the best option, since it will show it for exactly your target, instead of just a target that's "close enough" (e.g. for winit I'd have to pick x86_64-apple-darwin on docs.rs even though I'm currently using aarch64-apple-darwin)).

kchibisov · 2023-09-03T22:45:47Z

@madsmtm you can just pass --target to like anything and get the docs you want. If something. It's a bit weird when it comes to discoverability, indeed, but it's not like if we change something the ecosystem will change.

Also, have you looked into how rust does the docs in stdlib? They have #[doc(cfg(windows))] stuff and it somehow shows, but tells me explicitly that the thing is only available with windows right when I try to look into stuff. Though, maybe rust just builds docs differently?

daxpedda · 2023-09-04T09:54:37Z

I think "I'm not used to seeing the other platforms in the documentation" should be trumped by "increased discovery of platform-specific APIs in a cross-platform library".

About the maintenance issue: @madsmtm has done good effort in putting this together and it seems quite straightforward to me. The way Winit is structured lends itself incredibly well to this system, because we have separated the files so neatly.

I'm still strongly in favor of this change. But I acknowledge this comes with a maintenance burden, which I believe considering the benefits and the current structure of Winit is negligible.

Cc rust-lang/rust#1998.

kchibisov · 2023-09-07T06:32:16Z

@madsmtm the issue I have after this change, is that it looks like this:

So I have no information whatsoever to determine what is available for me and what is not. I was just using cargo doc and that's what I use daily to see the docs.

kchibisov · 2023-09-07T06:37:21Z

Yeah, you need nightly for that and doc_auto_cfg, so the change is not applicable for us.

daxpedda · 2023-09-07T08:20:22Z

So I have no information whatsoever to determine what is available for me and what is not. I was just using cargo doc and that's what I use daily to see the docs.

I agree, that is a problem.

@madsmtm shouldn't we be able to only expose all other platforms when we also require doc_auto_cfg? E.g. with cfg(docsrs)?

This re-works the portable `run()` API that consumes the `EventLoop` and runs the loop on the calling thread until the app exits. This can be supported across _all_ platforms and compared to the previous `run() -> !` API is now able to return a `Result` status on all platforms except iOS and Web. Fixes: #2709 By moving away from `run() -> !` we stop calling `std::process::exit()` internally as a means to kill the process without returning which means it's possible to return an exit status and applications can return from their `main()` function normally. This also fixes Android support where an Activity runs in a thread but we can't assume to have full ownership of the process (other services could be running in separate threads). Additionally all examples have generally been updated so that `main()` returns a `Result` from `run()` Fixes: #2709

MarijnS95 · 2023-10-24T23:01:13Z

Looking forward to seeing this, especially in light of #3178, though hope it doesn't conflict too badly 😅

E.g. there is some docs pointing from run_on_demand (non-wasm!) to a wasm-only spawn() feature/function, which seems a bit confusing.

madsmtm · 2023-12-24T10:07:37Z

shouldn't we be able to only expose all other platforms when we also require doc_auto_cfg? E.g. with cfg(docsrs)?

Apologies for the delay, I've done so now.

daxpedda

Thank you for doing this, this is so cool!

src/platform/web.rs

src/lib.rs

src/platform/web.rs

src/platform/android.rs

daxpedda

LGTM!

This required a few ugly hacks, such as making some #[doc(hidden)] empty structs on platforms where we expose some external dependency - but I tend to think that's a somewhat good thing, since it makes it more explicit that we have a public dependency here.

Co-authored-by: daxpedda <daxpedda@gmail.com>

madsmtm added S - docs Awareness, docs, examples, etc. S - platform parity Unintended platform differences S - maintenance Repaying technical debt labels Sep 1, 2023

madsmtm requested review from msiglreith, daxpedda and kchibisov as code owners September 1, 2023 10:44

madsmtm requested review from notgull and removed request for daxpedda, msiglreith and kchibisov September 1, 2023 10:45

madsmtm commented Sep 1, 2023

View reviewed changes

daxpedda approved these changes Sep 2, 2023

View reviewed changes

src/lib.rs Outdated Show resolved Hide resolved

MarijnS95 mentioned this pull request Oct 25, 2023

On wasm, provide intradoc-link for spawn() function in EventLoop docs #3178

Merged

madsmtm mentioned this pull request Nov 22, 2023

Build docs on docs.rs for iOS and Android as well #2324

Merged

5 tasks

madsmtm force-pushed the docsrs-all-platforms branch 2 times, most recently from 3eed152 to 85d3ef0 Compare December 24, 2023 10:07

madsmtm force-pushed the docsrs-all-platforms branch from 85d3ef0 to 77780f7 Compare December 24, 2023 10:17

madsmtm changed the title ~~Doc: Always display platform-specific documentation~~ Display all platform-specific documentation on docs.rs Dec 24, 2023

daxpedda requested changes Dec 24, 2023

View reviewed changes

src/platform/web.rs Outdated Show resolved Hide resolved

src/lib.rs Show resolved Hide resolved

src/platform/web.rs Show resolved Hide resolved

src/platform/android.rs Outdated Show resolved Hide resolved

madsmtm force-pushed the docsrs-all-platforms branch from 77780f7 to f43bfde Compare December 25, 2023 17:40

madsmtm requested a review from daxpedda December 25, 2023 17:41

daxpedda approved these changes Dec 25, 2023

View reviewed changes

madsmtm force-pushed the docsrs-all-platforms branch from f43bfde to 97c74a2 Compare December 25, 2023 17:53

madsmtm requested a review from kchibisov December 25, 2023 17:54

daxpedda force-pushed the docsrs-all-platforms branch from 97c74a2 to 3a23182 Compare January 4, 2024 11:43

madsmtm and others added 4 commits January 4, 2024 12:48

Implement modifier supplement and scancode traits at the top level

bab449f

Add CI step for testing that cross-platform documentation works

11bf002

Update after review

cab4211

Co-authored-by: daxpedda <daxpedda@gmail.com>

daxpedda force-pushed the docsrs-all-platforms branch from 3a23182 to cab4211 Compare January 4, 2024 11:48

daxpedda merged commit 42dbc47 into master Jan 4, 2024
51 checks passed

daxpedda deleted the docsrs-all-platforms branch January 4, 2024 11:54

This was referenced Jan 4, 2024

Test all docs.rs deployments #3356

Merged

Deploy master docs to GitHub Pages #3359

Merged

daxpedda mentioned this pull request Jul 10, 2024

Web: use the word "Web" correctly and consistently #3785

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Display all platform-specific documentation on docs.rs #3076

Display all platform-specific documentation on docs.rs #3076

madsmtm commented Sep 1, 2023 •

edited

Loading

madsmtm Sep 1, 2023

daxpedda left a comment

kchibisov commented Sep 3, 2023

madsmtm commented Sep 3, 2023

kchibisov commented Sep 3, 2023

madsmtm commented Sep 3, 2023

kchibisov commented Sep 3, 2023

daxpedda commented Sep 4, 2023 •

edited

Loading

kchibisov commented Sep 7, 2023

kchibisov commented Sep 7, 2023

daxpedda commented Sep 7, 2023

MarijnS95 commented Oct 24, 2023 •

edited

Loading

madsmtm commented Dec 24, 2023

daxpedda left a comment

daxpedda left a comment

		@@ -8,6 +8,7 @@ And please only add new entries to the top of this list, right below the `# Unre

		# Unreleased

		- Breaking: No longer export `platform::x11::XNotSupported`.

Display all platform-specific documentation on docs.rs #3076

Display all platform-specific documentation on docs.rs #3076

Conversation

madsmtm commented Sep 1, 2023 • edited Loading

madsmtm Sep 1, 2023

Choose a reason for hiding this comment

daxpedda left a comment

Choose a reason for hiding this comment

kchibisov commented Sep 3, 2023

madsmtm commented Sep 3, 2023

Motivation

kchibisov commented Sep 3, 2023

madsmtm commented Sep 3, 2023

kchibisov commented Sep 3, 2023

daxpedda commented Sep 4, 2023 • edited Loading

kchibisov commented Sep 7, 2023

kchibisov commented Sep 7, 2023

daxpedda commented Sep 7, 2023

MarijnS95 commented Oct 24, 2023 • edited Loading

madsmtm commented Dec 24, 2023

daxpedda left a comment

Choose a reason for hiding this comment

daxpedda left a comment

Choose a reason for hiding this comment

madsmtm commented Sep 1, 2023 •

edited

Loading

daxpedda commented Sep 4, 2023 •

edited

Loading

MarijnS95 commented Oct 24, 2023 •

edited

Loading