Add doc aliases for print macros #79232

yoshuawuyts · 2020-11-20T14:08:42Z

Adds a variety of doc aliases for our print macros: "echo" for PHP and Bash. "print" for PHP and Lua, "printf" for C and C++, "console.log" for JavaScript. This only serves to make them easier to find in the doc search. Thanks!

rust-highfive · 2020-11-20T14:08:45Z

r? @Mark-Simulacrum

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

yoshuawuyts · 2020-11-20T14:36:34Z

I've added puts for Ruby as suggested here and log as a general keyword since "logging" is a commonly used umbrella term for all the APIs we're describing here.

yoshuawuyts · 2020-11-20T14:51:36Z

Also added a "println" alias to dbg so that when you search for "println" in the docs you also find dbg. This is what the output looks like right now:

"echo" for PHP and Bash. "print" for PHP and Lua, "printf" for C and C++, "console.log" for JavaScript

yoshuawuyts · 2020-11-21T15:08:04Z

It seems we're having a doc failure here; I can't render docs locally -- so I'm not sure what the right ordering here ought to be so I can make the tests pass.

Error

Checking "macro-print" ... FAILED
==> '{"path":"std","name":"dbg"}' was supposed to be before '{"crate":"std","name":"dbg","path":"std","desc":"Prints and returns the value of a given expression for…","ty":14,"type":null,"is_alias":true,"alias":"macro:print","displayPath":"<span>std::</span>","fullPath":"<span>std::</span>dbg","href":"../std/macro.dbg.html"}'
==> '{"path":"std","name":"eprint"}' was supposed to be before '{"crate":"std","name":"eprint","path":"std","desc":"Prints to the standard error.","ty":14,"type":null,"is_alias":true,"alias":"macro:print","displayPath":"<span>std::</span>","fullPath":"<span>std::</span>eprint","href":"../std/macro.eprint.html"}'
==> '{"path":"std","name":"println"}' was supposed to be before '{"crate":"std","name":"println","path":"std","desc":"Prints to the standard output, with a newline.","ty":14,"type":null,"is_alias":true,"alias":"macro:print","displayPath":"<span>std::</span>","fullPath":"<span>std::</span>println","href":"../std/macro.println.html"}'
==> '{"path":"std","name":"eprintln"}' was supposed to be before '{"crate":"std","name":"eprintln","path":"std","desc":"Prints to the standard error, with a newline.","ty":14,"type":null,"is_alias":true,"alias":"macro:print","displayPath":"<span>std::</span>","fullPath":"<span>std::</span>eprintln","href":"../std/macro.eprintln.html"}'

Mark-Simulacrum · 2020-11-22T21:32:34Z

I guess it's looking for a prefix?

GuillaumeGomez · 2020-12-04T15:51:29Z

Considering it's doc changes, please ping the @rust-lang/docs (or the @rust-lang/rustdoc) teams in the future. Strongly like the idea though!

GuillaumeGomez · 2020-12-04T16:01:36Z

library/std/src/macros.rs

@@ -55,6 +55,12 @@ macro_rules! panic {
 /// io::stdout().flush().unwrap();
 /// ```
 #[macro_export]
+#[doc(alias = "echo")]
+#[doc(alias = "print")]


Kinda useless no? :p

GuillaumeGomez · 2020-12-04T16:02:22Z

library/std/src/macros.rs

@@ -88,6 +94,12 @@ macro_rules! print {
 /// println!("format {} arguments", "some");
 /// ```
 #[macro_export]
+#[doc(alias = "echo")]
+#[doc(alias = "print")]


I don't think it's a good idea to add this alias. They'll find the print macro which talks about the println one.

GuillaumeGomez · 2020-12-04T16:02:41Z

library/std/src/macros.rs

@@ -119,6 +131,12 @@ macro_rules! println {
 /// eprint!("Error: Could not complete task");
 /// ```
 #[macro_export]
+#[doc(alias = "echo")]
+#[doc(alias = "print")]


Wouldn't add it.

GuillaumeGomez · 2020-12-04T16:02:49Z

library/std/src/macros.rs

@@ -147,6 +165,12 @@ macro_rules! eprint {
 /// eprintln!("Error: Could not complete task");
 /// ```
 #[macro_export]
+#[doc(alias = "echo")]
+#[doc(alias = "print")]


Wouldn't add it.

GuillaumeGomez · 2020-12-04T16:02:57Z

library/std/src/macros.rs

@@ -280,6 +304,13 @@ macro_rules! eprintln {
 /// [`debug!`]: https://docs.rs/log/*/log/macro.debug.html
 /// [`log`]: https://crates.io/crates/log
 #[macro_export]
+#[doc(alias = "echo")]
+#[doc(alias = "print")]


Wouldn't add it.

GuillaumeGomez · 2020-12-04T16:03:29Z

src/test/rustdoc-js-std/macro-print.js

@@ -3,6 +3,7 @@ const QUERY = 'macro:print';
 const EXPECTED = {
    'others': [
        { 'path': 'std', 'name': 'print' },
+        { 'path': 'std', 'name': 'dbg' },


Why this change?

GuillaumeGomez

Please add more rustdoc-js-std tests for the newly added aliases. You can make multiple tests in one file if you want (take a look at rustdoc-js/doc-alias.js to see how).

yoshuawuyts · 2020-12-18T15:52:53Z

I'm actually having second thoughts about these changes. That together with the process to landing it being more involved than I'd hoped it would be (tests require some effort) I think the best path forward for me here now is to close it. Perhaps someone more motivated than me can pick this back up in the future.

jyn514 · 2020-12-18T16:12:41Z

@GuillaumeGomez I think your review was a lot more strict than it needed to be - I really don't think it makes sense for every doc(alias) change to need tests.

Mark-Simulacrum · 2020-12-18T16:12:42Z

Why do we need tests for the added aliases? I am confused - we do not generally test documentation in specific, just that a feature works...

GuillaumeGomez · 2020-12-18T16:18:39Z

I agree: after talking with other people, it seems a bit unnecessary. The only thing to do in the end is to add the doc-alias label on the PR so we can keep track of them in case we need to update the feature itself (very unlikely but who knows?).

Sorry about the confusion.

GuillaumeGomez · 2020-12-18T16:19:23Z

My code comments still need answers/updates though. ;)

rust-log-analyzer · 2020-12-18T16:54:19Z

The job x86_64-gnu-llvm-9 failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

GITHUB_ENV=/home/runner/work/_temp/_runner_file_commands/set_env_cd4d2b08-ea1c-4263-8f21-454e91eed318
GITHUB_EVENT_NAME=pull_request
GITHUB_EVENT_PATH=/home/runner/work/_temp/_github_workflow/event.json
GITHUB_GRAPHQL_URL=https://api.github.com/graphql
GITHUB_HEAD_REF=printf-alias
GITHUB_JOB=pr
GITHUB_PATH=/home/runner/work/_temp/_runner_file_commands/add_path_cd4d2b08-ea1c-4263-8f21-454e91eed318
GITHUB_REF=refs/pull/79232/merge
GITHUB_REPOSITORY_OWNER=rust-lang
GITHUB_RETENTION_DAYS=90
GITHUB_RUN_ID=430859652
GITHUB_RUN_NUMBER=21619
---
Collecting six>=1.5 (from python-dateutil<3.0.0,>=2.1; python_version >= "2.7"->botocore==1.12.197->awscli)
Building wheels for collected packages: PyYAML
  Running setup.py bdist_wheel for PyYAML: started
  Running setup.py bdist_wheel for PyYAML: finished with status 'error'
  Complete output from command /usr/bin/python3 -u -c "import setuptools, tokenize;__file__='/tmp/pip-build-34nmcu7q/PyYAML/setup.py';f=getattr(tokenize, 'open', open)(__file__);code=f.read().replace('\r\n', '\n');f.close();exec(compile(code, __file__, 'exec'))" bdist_wheel -d /tmp/tmp7id7lrbfpip-wheel- --python-tag cp36:
     or: -c --help [cmd1 cmd2 ...]
     or: -c --help-commands
     or: -c cmd --help
  
---
.................................................................................................... 9000/11178
.................................................................................................... 9100/11178
......................................................................i......i...................... 9200/11178
.................................................................................................... 9300/11178
.........iiiiii..iiiiii.i........................................................................... 9400/11178
.................................................................................................... 9600/11178
.................................................................................................... 9700/11178
.................................................................................................... 9800/11178
.................................................................................................... 9900/11178
---
Suite("src/test/assembly") not skipped for "bootstrap::test::Assembly" -- not in ["src/tools/tidy"]
Check compiletest suite=assembly mode=assembly (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)

running 27 tests
iiiiiiiiiiiiiiiiiiiiiiiiiii

 finished in 0.066 seconds
Suite("src/test/incremental") not skipped for "bootstrap::test::Incremental" -- not in ["src/tools/tidy"]
Check compiletest suite=incremental mode=incremental (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
---
Suite("src/test/debuginfo") not skipped for "bootstrap::test::Debuginfo" -- not in ["src/tools/tidy"]
Check compiletest suite=debuginfo mode=debuginfo (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)

running 116 tests
iiiiiiiiii.i.i..i..i...ii...i.i....ii..........iiii..........i....i...i.......ii.i.ii.....iiii.....i 100/116
test result: ok. 78 passed; 0 failed; 38 ignored; 0 measured; 0 filtered out; finished in 2.32s

 finished in 2.387 seconds
Suite("src/test/ui-fulldeps") not skipped for "bootstrap::test::UiFullDeps" -- not in ["src/tools/tidy"]
---
Checking "from_u" ... OK
Checking "keyword" ... OK
Checking "macro-check" ... OK
Checking "macro-print" ... FAILED
==> '{"path":"std","name":"dbg"}' was supposed to be before '{"crate":"std","name":"dbg","path":"std","desc":"Prints and returns the value of a given expression for …","ty":14,"type":null,"is_alias":true,"alias":"macro:print","displayPath":"<span>std::</span>","fullPath":"<span>std::</span>dbg","href":"../std/macro.dbg.html"}'
==> '{"path":"std","name":"eprint"}' was supposed to be before '{"crate":"std","name":"eprint","path":"std","desc":"Prints to the standard error.","ty":14,"type":null,"is_alias":true,"alias":"macro:print","displayPath":"<span>std::</span>","fullPath":"<span>std::</span>eprint","href":"../std/macro.eprint.html"}'
==> '{"path":"std","name":"println"}' was supposed to be before '{"crate":"std","name":"println","path":"std","desc":"Prints to the standard output, with a newline.","ty":14,"type":null,"is_alias":true,"alias":"macro:print","displayPath":"<span>std::</span>","fullPath":"<span>std::</span>println","href":"../std/macro.println.html"}'
==> '{"path":"std","name":"eprintln"}' was supposed to be before '{"crate":"std","name":"eprintln","path":"std","desc":"Prints to the standard error, with a newline.","ty":14,"type":null,"is_alias":true,"alias":"macro:print","displayPath":"<span>std::</span>","fullPath":"<span>std::</span>eprintln","href":"../std/macro.eprintln.html"}'
Checking "never" ... OK
Checking "quoted" ... OK
Checking "return-specific-literal" ... OK
Checking "return-specific" ... OK
Checking "return-specific" ... OK
Checking "should-fail" ... OK
Checking "string-from_ut" ... OK
Checking "struct-vec" ... OK
Checking "vec-new" ... OK


command did not execute successfully: "/usr/bin/node" "/checkout/src/tools/rustdoc-js/tester.js" "--crate-name" "std" "--resource-suffix" "1.50.0" "--doc-folder" "/checkout/obj/build/x86_64-unknown-linux-gnu/doc" "--test-folder" "/checkout/src/test/rustdoc-js-std"


failed to run: /checkout/obj/build/bootstrap/debug/bootstrap --stage 2 test --exclude src/tools/tidy
Build completed unsuccessfully in 0:34:10

Dylan-DPC-zz · 2021-01-13T02:17:06Z

@yoshuawuyts any updates on this?

crlf0710 · 2021-01-29T11:43:22Z

@yoshuawuyts Triage: I'm closing this due to inactivity. Feel free to reopen or create a new pr when you have time to work on this again. Thanks!

rust-highfive assigned Mark-Simulacrum Nov 20, 2020

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Nov 20, 2020

Add doc aliases for print macros

6470cd3

"echo" for PHP and Bash. "print" for PHP and Lua, "printf" for C and C++, "console.log" for JavaScript

Mark-Simulacrum added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Nov 22, 2020

GuillaumeGomez reviewed Dec 4, 2020

View reviewed changes

GuillaumeGomez requested changes Dec 4, 2020

View reviewed changes

yoshuawuyts closed this Dec 18, 2020

GuillaumeGomez reopened this Dec 18, 2020

GuillaumeGomez removed the A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools label Dec 18, 2020

GuillaumeGomez removed the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Dec 18, 2020

JohnCSimon added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jan 11, 2021

crlf0710 closed this Jan 29, 2021

crlf0710 added S-inactive Status: Inactive and waiting on the author. This is often applied to closed PRs. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jan 29, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add doc aliases for print macros #79232

Add doc aliases for print macros #79232

yoshuawuyts commented Nov 20, 2020

rust-highfive commented Nov 20, 2020

yoshuawuyts commented Nov 20, 2020

yoshuawuyts commented Nov 20, 2020

yoshuawuyts commented Nov 21, 2020

Mark-Simulacrum commented Nov 22, 2020

GuillaumeGomez commented Dec 4, 2020

GuillaumeGomez Dec 4, 2020

GuillaumeGomez Dec 4, 2020

GuillaumeGomez Dec 4, 2020

GuillaumeGomez Dec 4, 2020

GuillaumeGomez Dec 4, 2020

GuillaumeGomez Dec 4, 2020

GuillaumeGomez left a comment

yoshuawuyts commented Dec 18, 2020

jyn514 commented Dec 18, 2020

Mark-Simulacrum commented Dec 18, 2020

GuillaumeGomez commented Dec 18, 2020

GuillaumeGomez commented Dec 18, 2020

rust-log-analyzer commented Dec 18, 2020

Dylan-DPC-zz commented Jan 13, 2021

crlf0710 commented Jan 29, 2021

Add doc aliases for print macros #79232

Add doc aliases for print macros #79232

Conversation

yoshuawuyts commented Nov 20, 2020

rust-highfive commented Nov 20, 2020

yoshuawuyts commented Nov 20, 2020

yoshuawuyts commented Nov 20, 2020

yoshuawuyts commented Nov 21, 2020

Error

Mark-Simulacrum commented Nov 22, 2020

GuillaumeGomez commented Dec 4, 2020

GuillaumeGomez Dec 4, 2020

Choose a reason for hiding this comment

GuillaumeGomez Dec 4, 2020

Choose a reason for hiding this comment

GuillaumeGomez Dec 4, 2020

Choose a reason for hiding this comment

GuillaumeGomez Dec 4, 2020

Choose a reason for hiding this comment

GuillaumeGomez Dec 4, 2020

Choose a reason for hiding this comment

GuillaumeGomez Dec 4, 2020

Choose a reason for hiding this comment

GuillaumeGomez left a comment

Choose a reason for hiding this comment

yoshuawuyts commented Dec 18, 2020

jyn514 commented Dec 18, 2020

Mark-Simulacrum commented Dec 18, 2020

GuillaumeGomez commented Dec 18, 2020

GuillaumeGomez commented Dec 18, 2020

rust-log-analyzer commented Dec 18, 2020

Dylan-DPC-zz commented Jan 13, 2021

crlf0710 commented Jan 29, 2021