Source code on docs.rs: ambiguous and obscure

[programmerjake]

this makes me think that there should be a way for rustdoc's output to be merged with the source view so all files are present, it errors if rustdoc's output doesn't match the source (to catch malicious builds), and it just has rustdoc's extra features on the files that rustdoc processed, other files will just have code highlighting and that's it.

[kornel]

The default doc build is done on Linux, so a conditional include like this:

windows.rs - source

includes:

stub.rs - source

and you don't see windows/sys.rs in the file tree sidebar, as if the file didn't exist.

[bjorn3]

@programmerjake

this makes me think that there should be a way for rustdoc's output to be merged with the source view so all files are present, it errors if rustdoc's output doesn't match the source (to catch malicious builds), and it just has rustdoc's extra features on the files that rustdoc processed, other files will just have code highlighting and that's it.

That merging would have to be done outside of rustdoc and would need to apply a sanitizer to the rustdoc output to remove any display: none; or equivalent that could affect the source view in a way that confuses the user. Because of proc-macros getting loaded by rustdoc, the rustdoc source pages can contain arbitrary html and javascript.

[decathorpe]

@kornel

I've looked in detail into git<>crate correspondence and it's a mess:

You might be interested in ingredients which attempts to work around the mess to some degree, and give decently meaningful information. It seems to work well in testing against the ~3000 Rust crates we have packaged in Fedora Linux, and I'm working on integrating it into our packaging workflow.

But in general I agree with

@kornel

In the end you have to look at the same source that Cargo gets. Cargo doesn't get source from git, so trying to look at git will only make it a weaker, potentially misleading derivative. Making users aware where is the true content of a crate is technically way simpler than trying to build a secure chain between a git repo and what Cargo compiles (fetching via git protocol has a bunch of trust and perf issues)

and this is also why for Fedora packaging, we treat what is published to / distributed by cratesio as the canonical source for all Rust crates, and the tooling I'm working on is only supposed to provide immediate informational value (for example, knowing that the linked repository no longer exists can be valuable).

[Vorpal]

@kpreid

As far as I know, the displayed text of the files that are present will always be the same, modulo build-time malicious code.

What about generated code from build scripts? Things like protobufs in prost should presumably not vary by platform, but I could conceivably see cases where generated code varied by target platform rather than generating macros and cfgs to deal with that. Perhaps a reasonable example would be FFI bindings to OS libraries that vary by platform and specific version.