rustdoc: import cross-crate macros alongside everything else #51611

QuietMisdreavus · 2018-06-17T20:02:19Z

The thrilling conclusion of the cross-crate macro saga in rustdoc! After #51425 made sure we saw all the namespaces of an import (and prevented us from losing the vec! macro in std's documentation), here is the PR to handle cross-crate macro re-exports at the same time as everything else. This way, attributes like #[doc(hidden)] and #[doc(no_inline)] can be used to control how the documentation for these macros is seen, rather than rustdoc inlining every macro every time.

Fixes #50647

rust-highfive · 2018-06-17T20:02:29Z

r? @frewsxcv

(rust_highfive has picked a reviewer for you, use r? to override)

rust-highfive · 2018-06-17T21:07:23Z

The job x86_64-gnu-llvm-3.9 of your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

travis_time:start:test_rustdoc
Check compiletest suite=rustdoc mode=rustdoc (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
[01:00:43] 
[01:00:43] running 241 tests
[01:01:56] ..................F.i...............................................................................
[01:02:39] ..............i...................................................................................F.
[01:02:50] thread 'main' panicked at 'Some tests failed', tools/compiletest/src/main.rs:498:22
[01:02:50] failures:
[01:02:50] 
[01:02:50] ---- [rustdoc] rustdoc/cross-crate-links.rs stdout ----
[01:02:50] ---- [rustdoc] rustdoc/cross-crate-links.rs stdout ----
[01:02:50] 
[01:02:50] error: htmldocck failed!
[01:02:50] status: exit code: 1
[01:02:50] command: "/usr/bin/python2.7" "/checkout/src/etc/htmldocck.py" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc/cross-crate-links" "/checkout/src/test/rustdoc/cross-crate-links.rs"
[01:02:50] ------------------------------------------
[01:02:50] 
[01:02:50] ------------------------------------------
[01:02:50] stderr:
[01:02:50] stderr:
[01:02:50] ------------------------------------------
[01:02:50] 69: @has check failed
[01:02:50]  `XPATH PATTERN` did not match
[01:02:50]  // @has 'foo/index.html' '//a[@href="../foo/macro.foo_macro.html"]' 'foo_macro'
[01:02:50] Encountered 1 errors
[01:02:50] 
[01:02:50] ------------------------------------------
[01:02:50] 
[01:02:50] 
[01:02:50] thread '[rustdoc] rustdoc/cross-crate-links.rs' panicked at 'explicit panic', tools/compiletest/src/runtest.rs:3139:9
[01:02:50] note: R/stage2/lib/rustlib/x86_64-unknown-linux-gnu/lib" "--rustc-path" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/bin/rustc" "--rustdoc-path" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/bin/rustdoc" "--src-base" "/checkout/src/test/rustdoc" "--build-base" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc" "--stage-id" "stage2-x86_64-unknown-linux-gnu" "--mode" "rustdoc" "--target" "x86_64-unknown-linux-gnu" "--host" "x86_64-unknown-linux-gnu" "--llvm-filecheck" "/usr/lib/llvm-3.9/bin/FileCheck" "--host-rustcflags" "-Crpath -O -Zunstable-options " "--target-rustcflags" "-Crpath -O -Zunstable-options  -Lnative=/checkout/obj/build/x86_64-unknown-linux-gnu/native/rust-test-helpers" "--docck-python" "/usr/bin/python2.7" "--lldb-python" "/usr/bin/python2.7" "--gdb" "/usr/bin/gdb" "--quiet" "--llvm-version" "3.9.1\n" "--system-llvm" "--cc" "" "--cxx" "" "--cflags" "" "--llvm-components" "" "--llvm-cxxflags" "" "--adb-path" "adb" "--adb-test-dir" "/data/tmp/work" "--android-cross-path" "" "--color" "always"
[01:02:50] 
[01:02:50] 
[01:02:50] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test
[01:02:50] Build completed unsuccessfully in 0:22:33
[01:02:50] Build completed unsuccessfully in 0:22:33
[01:02:50] Makefile:58: recipe for target 'check' failed
[01:02:50] make: *** [check] Error 1

The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:399a0e12
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

hey look, macros properly link to the right place now

rust-highfive · 2018-06-17T22:39:11Z

The job x86_64-gnu-llvm-3.9 of your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

[01:06:45] failures:
[01:06:45] 
[01:06:45] ---- [rustdoc] rustdoc/pub-use-extern-macros.rs stdout ----
[01:06:45] 
[01:06:45] error: htmldocck failed!
[01:06:45] status: exit code: 1
[01:06:45] command: "/usr/bin/python2.7" "/checkout/src/etc/htmldocck.py" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc/pub-use-extern-macros" "/checkout/src/test/rustdoc/pub-use-extern-macros.rs"
[01:06:45] ------------------------------------------
[01:06:45] 
[01:06:45] ------------------------------------------
[01:06:45] stderr:
[01:06:45] stderr:
[01:06:45] ------------------------------------------
[01:06:45] 26: @has check failed
[01:06:45]  File does not exist 'pub_use_extern_macros/macro.quux.html'
[01:06:45]  // @has pub_use_extern_macros/macro.quux.html
[01:06:45] Encountered 1 errors
[01:06:45] 
[01:06:45] ------------------------------------------
[01:06:45] 
[01:06:45] 
[01:06:45] thread '[rustdoc] rustdoc/pub-use-extern-macros.rs' panicked at 'explicit panic', tools/compiletest/src/runtest.rs:3139:9
[01:06:45] 
[01:06:45] 
[01:06:45] failures:
[01:06:45]     [rustdoc] rustdoc/pub-use-extern-macrosd to run: /checkout/obj/build/bootstrap/debug/bootstrap test
[01:06:45] Build completed unsuccessfully in 0:23:39
[01:06:45] Makefile:58: recipe for target 'check' failed
[01:06:45] make: *** [check] Error 1

The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:0108d6d4
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
---
travis_time:end:08c441f4:start=1529275148382355537,finish=1529275148389598456,duration=7242919
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:01c7be57
$ head -30 ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers || true
head: cannot open ‘./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers’ for reading: No such file or directory
travis_fold:end:after_failure.4
travis_fold:start:after_failure.5
travis_time:start:09a5ea1c
$ dmesg | grep -i kill

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

ollie27 · 2018-06-18T05:15:37Z

src/librustdoc/clean/inline.rs

+    };
+
+    let source = format!("macro_rules! {} {{\n{}}}",
+                         def.ident.name.clean(cx),


This needs to use the name passed to try_inline so that things like pub use foo::foo_macro as bar_macro; will display bar_macro here.

I wonder if this is something we need to do for other imports. None of them are using the imported name either, and IIRC we have other issues regarding imported structs using the wrong name in impl pages.

I believe that's a different issue. The difference with macros is that the definition is being rendered here rather than in render.rs like all other item types.

pietroalbini · 2018-06-25T15:11:59Z

r? @ollie27 (also, review ping!)

ollie27 · 2018-06-25T17:29:40Z

r=me with a test for the renamed case.

QuietMisdreavus · 2018-07-03T15:41:12Z

@ollie27 Sorry for the delay; I've pushed a commit which updates the test.

ollie27 · 2018-07-04T16:22:44Z

@bors: r+

bors · 2018-07-04T16:22:45Z

📌 Commit 61dc03c has been approved by ollie27

bors · 2018-07-04T18:15:21Z

⌛ Testing commit 61dc03c with merge 4af9132...

rustdoc: import cross-crate macros alongside everything else The thrilling conclusion of the cross-crate macro saga in rustdoc! After #51425 made sure we saw all the namespaces of an import (and prevented us from losing the `vec!` macro in std's documentation), here is the PR to handle cross-crate macro re-exports at the same time as everything else. This way, attributes like `#[doc(hidden)]` and `#[doc(no_inline)]` can be used to control how the documentation for these macros is seen, rather than rustdoc inlining every macro every time. Fixes #50647

bors · 2018-07-04T20:20:55Z

☀️ Test successful - status-appveyor, status-travis
Approved by: ollie27
Pushing 4af9132 to master...

rustdoc: import cross-crate macros alongside everything else

d4387b3

rust-highfive assigned frewsxcv Jun 17, 2018

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jun 17, 2018

QuietMisdreavus mentioned this pull request Jun 17, 2018

rustdoc: pub use for macros is inlined too eagerly #50647

Closed

fix cross-crate-links test

5499797

hey look, macros properly link to the right place now

fix test pub-use-extern-macros

5e50950

ollie27 reviewed Jun 18, 2018

View reviewed changes

use the imported name when rendering an imported macro

a220321

test for renaming re-exported macros

61dc03c

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 4, 2018

bors merged commit 61dc03c into rust-lang:master Jul 4, 2018

ollie27 mentioned this pull request Jul 8, 2018

ICE "attempting to document proc-macro re-export" #52129

Closed

QuietMisdreavus mentioned this pull request Aug 23, 2018

rustdoc: Macros re-exported via use_extern_macro appear as a re-export #49554

Closed

QuietMisdreavus deleted the slippery-macros branch November 15, 2018 15:50

bkchr mentioned this pull request Nov 28, 2018

Rustdoc issues with macro reexport #56173

Closed

LukasKalbertodt mentioned this pull request Feb 24, 2019

Writing testable documentation examples for proc macros is not possible #58700

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

rustdoc: import cross-crate macros alongside everything else #51611

rustdoc: import cross-crate macros alongside everything else #51611

QuietMisdreavus commented Jun 17, 2018

rust-highfive commented Jun 17, 2018

rust-highfive commented Jun 17, 2018

rust-highfive commented Jun 17, 2018

ollie27 Jun 18, 2018

QuietMisdreavus Jun 20, 2018

ollie27 Jun 25, 2018

pietroalbini commented Jun 25, 2018

ollie27 commented Jun 25, 2018

QuietMisdreavus commented Jul 3, 2018

ollie27 commented Jul 4, 2018

bors commented Jul 4, 2018

bors commented Jul 4, 2018

bors commented Jul 4, 2018

rustdoc: import cross-crate macros alongside everything else #51611

rustdoc: import cross-crate macros alongside everything else #51611

Conversation

QuietMisdreavus commented Jun 17, 2018

rust-highfive commented Jun 17, 2018

rust-highfive commented Jun 17, 2018

rust-highfive commented Jun 17, 2018

ollie27 Jun 18, 2018

Choose a reason for hiding this comment

QuietMisdreavus Jun 20, 2018

Choose a reason for hiding this comment

ollie27 Jun 25, 2018

Choose a reason for hiding this comment

pietroalbini commented Jun 25, 2018

ollie27 commented Jun 25, 2018

QuietMisdreavus commented Jul 3, 2018

ollie27 commented Jul 4, 2018

bors commented Jul 4, 2018

bors commented Jul 4, 2018

bors commented Jul 4, 2018