Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add doc aliases for print macros #79232

Closed
wants to merge 1 commit into from

Conversation

yoshuawuyts
Copy link
Member

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
Copy link
Collaborator

r? @Mark-Simulacrum

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

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Nov 20, 2020
@yoshuawuyts yoshuawuyts force-pushed the printf-alias branch 2 times, most recently from eaf7112 to 8c8371b Compare November 20, 2020 14:35
@yoshuawuyts
Copy link
Member Author

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
Copy link
Member Author

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:

Screenshot_2020-11-20 Results for println - Rust

"echo" for PHP and Bash. "print" for PHP and Lua, "printf" for C and C++, "console.log" for JavaScript
@yoshuawuyts
Copy link
Member Author

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
Copy link
Member

image

I guess it's looking for a prefix?

@Mark-Simulacrum 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
Copy link
Member

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 GuillaumeGomez added A-rustdoc-search Area: Rustdoc's search feature A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-doc-alias Area: #[doc(alias)] and removed A-rustdoc-search Area: Rustdoc's search feature labels Dec 4, 2020
@@ -55,6 +55,12 @@ macro_rules! panic {
/// io::stdout().flush().unwrap();
/// ```
#[macro_export]
#[doc(alias = "echo")]
#[doc(alias = "print")]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Kinda useless no? :p

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wouldn't add it.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wouldn't add it.

@@ -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")]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wouldn't add it.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why this change?

Copy link
Member

@GuillaumeGomez GuillaumeGomez left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member Author

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
Copy link
Member

jyn514 commented Dec 18, 2020

@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
Copy link
Member

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
Copy link
Member

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 GuillaumeGomez removed A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Dec 18, 2020
@GuillaumeGomez
Copy link
Member

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

@rust-log-analyzer
Copy link
Collaborator

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

@JohnCSimon 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
@Dylan-DPC-zz
Copy link

@yoshuawuyts any updates on this?

@crlf0710
Copy link
Member

@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!

@crlf0710 crlf0710 closed this Jan 29, 2021
@crlf0710 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-doc-alias Area: #[doc(alias)] S-inactive Status: Inactive and waiting on the author. This is often applied to closed PRs.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

9 participants