rustdoc: Add more test coverage

[camelid]

Summary

Currently, rustdoc doesn't have much test coverage, but it does have a lot of edge cases. We would like to have more test coverage, so we can improve the code with less risk of introducing bugs.

It's even helpful to add tests for incorrect behavior since it will help us find, fix, and test the fixes for bugs.

What to test

• Behavior of re-exports (e.g., pub use self::foo::bar) and inlining (some re-exports are rendered as re-exports, while others have their docs copied as if the re-export is the definition)
• Trait implementations, including normal impls, blanket impls (e.g., impl<T> MyTrait for &T), and auto impls (like Sized, Send, and Sync)
• Notable traits popup (appears as an (i) next to return types); it has some bugs currently that would be good to fix.

How to test

Here is the documentation for rustdoc's main tests (the tests in src/test/rustdoc):

rust/src/etc/htmldocck.py

Lines 28 to 100 in 49d4232

	# Commands
	Commands start with an `@` followed by a command name (letters and
	hyphens), and zero or more arguments separated by one or more whitespace
	characters and optionally delimited with single or double quotes. The `@`
	mark cannot be preceded by a non-whitespace character. Other lines
	(including every text up to the first `@`) are ignored, but it is
	recommended to avoid the use of `@` in the template file.
	There are a number of supported commands:
	* `@has PATH` checks for the existence of the given file.
	`PATH` is relative to the output directory. It can be given as `-`
	which repeats the most recently used `PATH`.
	* `@has PATH PATTERN` and `@matches PATH PATTERN` checks for
	the occurrence of the given pattern `PATTERN` in the specified file.
	Only one occurrence of the pattern is enough.
	For `@has`, `PATTERN` is a whitespace-normalized (every consecutive
	whitespace being replaced by one single space character) string.
	The entire file is also whitespace-normalized including newlines.
	For `@matches`, `PATTERN` is a Python-supported regular expression.
	The file remains intact but the regexp is matched without the `MULTILINE`
	and `IGNORECASE` options. You can still use a prefix `(?m)` or `(?i)`
	to override them, and `\A` and `\Z` for definitely matching
	the beginning and end of the file.
	(The same distinction goes to other variants of these commands.)
	* `@has PATH XPATH PATTERN` and `@matches PATH XPATH PATTERN` checks for
	the presence of the given XPath `XPATH` in the specified HTML file,
	and also the occurrence of the given pattern `PATTERN` in the matching
	node or attribute. Only one occurrence of the pattern in the match
	is enough.
	`PATH` should be a valid and well-formed HTML file. It does *not*
	accept arbitrary HTML5; it should have matching open and close tags
	and correct entity references at least.
	`XPATH` is an XPath expression to match. The XPath is fairly limited:
	`tag`, `*`, `.`, `//`, `..`, `[@attr]`, `[@attr='value']`, `[tag]`,
	`[POS]` (element located in given `POS`), `[last()-POS]`, `text()`
	and `@attr` (both as the last segment) are supported. Some examples:
	- `//pre` or `.//pre` matches any element with a name `pre`.
	- `//a[@href]` matches any element with an `href` attribute.
	- `//*[@class="impl"]//code` matches any element with a name `code`,
	which is an ancestor of some element which `class` attr is `impl`.
	- `//h1[@class="fqn"]/span[1]/a[last()]/@class` matches a value of
	`class` attribute in the last `a` element (can be followed by more
	elements that are not `a`) inside the first `span` in the `h1` with
	a class of `fqn`. Note that there cannot be any additional elements
	between them due to the use of `/` instead of `//`.
	Do not try to use non-absolute paths, it won't work due to the flawed
	ElementTree implementation. The script rejects them.
	For the text matches (i.e. paths not ending with `@attr`), any
	subelements are flattened into one string; this is handy for ignoring
	highlights for example. If you want to simply check for the presence of
	a given node or attribute, use an empty string (`""`) as a `PATTERN`.
	* `@count PATH XPATH COUNT' checks for the occurrence of the given XPath
	in the specified file. The number of occurrences must match the given
	count.
	* `@has-dir PATH` checks for the existence of the given directory.
	All conditions can be negated with `!`. `@!has foo/type.NoSuch.html`
	checks if the given file does not exist, for example.

You may also want to look at some existing tests in src/test/rustdoc.

Please note that you do not need to check that rustdoc's behavior is correct. We will check during code review, and as mentioned earlier, tests for incorrect behavior can be helpful too.

If you have any questions or get stuck, please ask here or on Zulip in #rustdoc!

[camelid]

cc @rust-lang/rustdoc

[cameron1024]

@rustbot claim

[jyn514]

@cameron1024 Since this is a tracking issue, I don't think it makes sense to claim - I plan to add some examples of tests soon, and it's definitely possible for multiple people to work on it in parallel :) feel free to work on it in the meantime though!