rustdoc
rustdoc copied to clipboard
steveklabnik
Become flag-compatible with existing rustdoc
https://github.com/rust-lang/rust/blob/master/src/doc/rustdoc/src/command-line-arguments.md describes the flags that current rustdoc accepts. For each flag, we should:
- Decide if we want to keep the flag or not
- For the ones we may not keep, implement them, but issue a warning
- For the ones we do, implement them!
I'm going to make an isssue per flag, as we should have those discussions individually.
I think there's a bit of an mismatch between the fact that old rustdoc allows documenting individual files while the new rustdoc expects a crate with Cargo.toml. How do we want to handle that?
Another way of putting it is that the old rustdoc expects to be wrapped by cargo, while the new rustdoc expects to wrap cargo.
@euclio that deserves to be its own ticket; we should deal with it as well. If you don't open one by Monday, I will 😄
Should this be its own milestone? It will proably make it easier to track all of these flag issues :grinning:
Maybe; for now, I've put this one on the relevant milestone. So that'd be like, a sub-milestone. IDK 😄
Some of these flags, such as library-path, moved from being a flag at the top level to being a flag for the build subcommand. I started down an approach to throw an error telling the user the flag moved. Another example is that --test is now a subcommand test. Do we want to provide this level of error message or do we think people will figure it out on their own?
I probably need to chat with some folks in IRC about how we want these flags to work. See https://github.com/steveklabnik/rustdoc/issues/141#issuecomment-348743115 which discusses how --test-args should work. I also now wonder if --output should be under the build subcommand or at the top level with --manifest-path. See my implementation https://github.com/steveklabnik/rustdoc/pull/216 to make sure my flag infrastructure PR worked.