cargo clean -p package can clear the document of a single crates

[heisen-li]

The current command cannot delete the document of a single crates. It is simple to delete the document in the directory. However, the previously generated index still needs to be modified or rebuilt, otherwise a large number of broken links will be left.

Regarding this part, I think of two methods:

1. Directly modify the generated index content;
2. Rebuild the doc to cover the previous content.

Am I complicating the problem? Do you have any suggestions?

close #8790

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @Eh2406 (or someone else) soon.

Please see the contribution instructions for more information.

[ehuss]

I don't think this needs to bother with updating the index or anything like that. I think just deleting the directory is fine.

[heisen-li]

I don't think this needs to bother with updating the index or anything like that. I think just deleting the directory is fine.

I'm very sorry, but I don't seem to fully understand you.
Just add the deletion of the target/doc directory? Do I understand correctly?
Is this the same as the cargo clean doc command?

[ehuss]

Oh, I meant just the package's doc directory (doc/foo or whatever).

[ehuss]

I think also that this should probably handle the interaction between -p and --doc, such that it would only clean the doc directory for the given package. Currently it seems to ignore the -p flag.

[heisen-li]

I have finished modifying and testing the deleted files.

[ehuss]

This isn't using the correct name here. The directory names are the crate names of the targets. I'm uncertain about the best way to handle this, but specifically:

• Non-workspace members can only have library targets documented, so that would be something like pkg.library().map(|t| t.crate_name()). I think it could be dangerous to blindly remove directories for other targets like "examples" because there could be name collisions (for example, if something has an example called "serde", it would delete the serde directory, which is probably not what you want).
• For workspace members, it is possible to document binaries (and now examples due to Adding the cargo doc --examples subcommand #9808). So to clean a package, it would need to delete all documentable targets. Unfortunately this runs afoul with the "serde" example, too, so maybe just deleting libraries is sufficient? I'm still not entirely clear on the motivation for cleaning these, so I'm uncertain if it is important or not.

[heisen-li]

I think it could be dangerous to blindly remove directories for other targets like "examples" because there could be name collisions (for example, if something has an example called "serde", it would delete the serde directory, which is probably not what you want).

I'm sorry, I don't quite understand your question. Could you explain it again?

For workspace members, it is possible to document binaries (and now examples due to Adding the cargo doc --examples subcommand #9808). So to clean a package, it would need to delete all documentable targets. Unfortunately this runs afoul with the "serde" example, too, so maybe just deleting libraries is sufficient? I'm still not entirely clear on the motivation for cleaning these, so I'm uncertain if it is important or not.

I'm sorry. I really didn't think of the question in advance. If the example name in the ../examples/ folder is the same as another crate name, this should be taken into account.

Also, I'm not sure I understood this correctly: Is the current question the same as you stated above (about the example name conflicts with the crate name)?

[ehuss]

Yea, both points are related to one another.

The doc directories are based on a target's crate name. So, for example, if I have a package named "foo" with a "foo" library and a "foo-cli" binary, there would be two directories:

• doc/foo
• doc/foo_cli

To clean this properly, it would need to iterate over all documentable targets and get their crate names. Don't forget that the package name, the target name, and the crate name can all be different. That is, package "abc-rs" can have a library named "my-abc-lib" which has a crate name of "my_abc_lib".

However, I'd be concerned about indiscriminately iterating over a package's targets because of name collisions. Imagine my "foo" library had a dependency on "serde", and a dependency on another package named "bar". I run cargo doc and also get the documentation for doc/foo, doc/serde, and doc/bar. Now, imagine bar had an binary coincidentally named serde, if a user runs cargo clean -p bar, we don't want to blow away the serde directory just because bar had a serde binary.

So, I'm thinking, to avoid deleting the wrong things, one step would be to only look for library targets of non-workspace dependencies. That should limit the collateral damage.

Then, I'm wondering about limiting the collateral damage of workspace members, too. Perhaps including examples is overkill, and perhaps it should only delete library crate names? Or maybe libraries + binaries? Or maybe it is fine to collect all targets with documented() is true. That's where I'm uncertain, since I'm not really sure I understand the need for this functionality.

I think I would lean towards just deleting the entries from pkg.targets().iter().filter(|t| t.documented()) for workspace members, and just the lib for non-members.

[heisen-li]

I need some time to think, please give me some time. i am sorry, huss.

[ehuss]

No worries, feel free to take your time, there's no rush. And let me know if you have any questions or if anything wasn't clear.

[heisen-li]

Sorry, I just ended my wedding leave. It was too late to reply.

However, I'd be concerned about indiscriminately iterating over a package's targets because of name collisions. Imagine my "foo" library had a dependency on "serde", and a dependency on another package named "bar". I run cargo doc and also get the documentation for doc/foo, doc/serde, and doc/bar. Now, imagine bar had an binary coincidentally named serde, if a user runs cargo clean -p bar, we don't want to blow away the serde directory just because bar had a serde binary.

This scenario was tested based on my understanding.

PS D:\Rust\temp\foo> cat .\Cargo.toml
...
[dependencies]
serde = "1.0.130"
bar = { path = "./bar"}

PS D:\Rust\temp\foo\bar> cat .\Cargo.toml
...
[[bin]]
name = "serde"
path = "./serde/src/main.rs"

The directory after cargo doc looks like this:

doc/bar
doc/foo
doc/serde

The binary files of serde and bar seem to have nothing to do with each other. In other words, the binary files under the bar directory will not form a document.

Therefore, running cargo clean -p bar only needs to delete doc/bar, and does not need to consider the conflict between the serde binary file under bar and the dependent serde of foo.
Is my understanding correct?

That's where I'm uncertain, since I'm not really sure I understand the need for this functionality.

My understanding of this function is:
If you execute cargo clean -p foo, you need to delete all doc/foo,doc/example_name,doc/dependence_name.
And these documents are in pkg.targets().iter().filter(|t| t.documented()).

I think I would lean towards just deleting the entries from pkg.targets().iter().filter(|t| t.documented()) for workspace members, and just the lib for non-members.

What does workspace member mean here?
Is this in Cargo.toml?

PS D:\Rust\temp\foo> cat .\Cargo.toml
...
[workspace]
members = ["member_1", "member_2", ...]

Frankly, I don't seem to fully understand workspace members and lib for non-members.

[ehuss]

What does workspace member mean here?

Essentially, yea, it is the members list. It's a little more complicated, since additional members can be inferred.

My understanding of this function is:
If you execute cargo clean -p foo, you need to delete all doc/foo,doc/example_name,doc/dependence_name.
And these documents are in pkg.targets().iter().filter(|t| t.documented()).

I think my question was: why does someone want to delete directories from the doc directory? What is the drawback of leaving them there? What is the use case for needing to delete them? Is it OK for it to only partially delete a package's data?

The binary files of serde and bar seem to have nothing to do with each other. In other words, the binary files under the bar directory will not form a document.

Therefore, running cargo clean -p bar only needs to delete doc/bar, and does not need to consider the conflict between the serde binary file under bar and the dependent serde of foo. Is my understanding correct?

I think what I'm trying to get at is that when you document a package, it documents the libraries and its binaries. If you have a package mypackage with binaries bar and baz, there will be three directories in the doc directory. To properly clean mypackage, it will need to iterate over all documentable targets and delete those directories. My concern is that could be too aggressive in some cases, as it could delete too much.

When cargo doc is run, it will document all documentable targets for workspace members, and all libraries for non-workspace members.

So my thought is that it would look for pkg.targets().iter().filter(|t| t.documented()) for workspace members, and pkg.targets().iter().find(|t| t.is_lib()) for non-members maybe?

[bors]

☔ The latest upstream changes (presumably #10072) made this pull request unmergeable. Please resolve the merge conflicts.

[heisen-li]

@ehuss Excuse me. I'm so sorry. Can you look at it again? I know this may be rude, but I wonder if I understand you correctly. To be honest, I'm a little fuzzy on this need now.