bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Auto merge of #45039 - QuietMisdreavus:doc-spotlight, r=GuillaumeGomez,QuietMisdreavus

Browse source 
show in docs whether the return type of a function impls Iterator/Read/Write

Closes #25928

This PR makes it so that when rustdoc documents a function, it checks the return type to see whether it implements a handful of specific traits. If so, it will print the impl and any associated types. Rather than doing this via a whitelist within rustdoc, i chose to do this by a new `#[doc]` attribute parameter, so things like `Future` could tap into this if desired.

### Known shortcomings

~~The printing of impls currently uses the `where` class over the whole thing to shrink the font size relative to the function definition itself. Naturally, when the impl has a where clause of its own, it gets shrunken even further:~~ (This is no longer a problem because the design changed and rendered this concern moot.)

The lookup currently just looks at the top-level type, not looking inside things like Result or Option, which renders the spotlights on Read/Write a little less useful:

<details><summary>`File::{open, create}` don't have spotlight info (pic of old design)</summary>

![image](https://user-images.githubusercontent.com/5217170/31209495-e59d027e-a950-11e7-9998-ceefceb71c07.png)

</details>

All three of the initially spotlighted traits are generically implemented on `&mut` references. Rustdoc currently treats a `&mut T` reference-to-a-generic as an impl on the reference primitive itself. `&mut Self` counts as a generic in the eyes of rustdoc. All this combines to create this lovely scene on `Iterator::by_ref`:

<details><summary>`Iterator::by_ref` spotlights Iterator, Read, and Write (pic of old design)</summary>

![image](https://user-images.githubusercontent.com/5217170/31209554-50b271ca-a951-11e7-928b-4f83416c8681.png)

</details>
This commit is contained in:
bors 2017-11-21 03:03:28 +00:00
commit 421a2113a8
13 changed files with 345 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

28
src/librustdoc/html/static/main.js
View file

@ -216,6 +216,7 @@
var help = document.getElementById("help");
switch (getVirtualKey(ev)) {
case "Escape":
hideModal();
var search = document.getElementById("search");
if (!hasClass(help, "hidden")) {
displayHelp(false, ev);
@ -229,6 +230,7 @@
case "s":
case "S":
displayHelp(false, ev);
hideModal();
ev.preventDefault();
focusSearchBar();
break;
@ -241,6 +243,7 @@
case "?":
if (ev.shiftKey) {
hideModal();
displayHelp(true, ev);
}
break;
@ -1713,6 +1716,31 @@
}
});
function showModal(content) {
var modal = document.createElement('div');
modal.id = "important";
addClass(modal, 'modal');
modal.innerHTML = '<div class="modal-content"><div class="close" id="modal-close">✕</div>' +
'<div class="whiter"></div><span class="docblock">' + content +
'</span></div>';
document.getElementsByTagName('body')[0].appendChild(modal);
document.getElementById('modal-close').onclick = hideModal;
modal.onclick = hideModal;
}
function hideModal() {
var modal = document.getElementById("important");
if (modal) {
modal.parentNode.removeChild(modal);
}
}
onEach(document.getElementsByClassName('important-traits'), function(e) {
e.onclick = function() {
showModal(e.lastElementChild.innerHTML);
};
});
var search_input = document.getElementsByClassName("search-input")[0];
if (search_input) {