document #[used] by japaric · Pull Request #361 · rust-lang/reference

japaric · 2018-06-20T15:03:08Z

I'm not 100% sure about grouping all those features under an "ABI" section, but having a single #[used] section seemed overkill. I'm open to suggestions about grouping features differently, e.g. using a different section name.

Required by rust-lang/rust#51363

steveklabnik · 2018-06-20T15:12:41Z

I'm not 100% sure about grouping all those features under an "ABI" section, but having a single #[used] section seemed overkill. I'm open to suggestions about grouping features differently, e.g. using a different section name.

Hmm, yeah. I feel.. the same. Wonder if anyone else has thoughts.

Havvy

An ABI page seems okay to me, especially with the outline of what goes there. The "used" page on the other hand is way too specific for its own page.

You'll also want to add the used attribute to the attributes page and link to where the documentation for it lands. I do think that ultimately all attribute docs should be scattered around the reference where they make sense and not just bunched into attributes.md, so having a few under abi.md sounds good to me.

Havvy · 2018-06-20T20:27:40Z

+
+The `#[used]` attribute can only be applied to `static` variables. This attribute forces the
+compiler to keep the variable in the output object file (.o, .rlib, etc.) even if the variable is
+not *used*, or referenced, by any other item in the crate. Without this attribute the compiler is


We use italics to denote definitions. But it doesn't look like "used" is being defined here.

Havvy · 2018-06-20T20:28:28Z

+
+The `#[used]` attribute can only be applied to `static` variables. This attribute forces the
+compiler to keep the variable in the output object file (.o, .rlib, etc.) even if the variable is
+not *used*, or referenced, by any other item in the crate. Without this attribute the compiler is


This whole line that starts with "Without" is literally just the negation of the previous statement, and feels extremely redundant to me.

Havvy · 2018-06-20T20:31:20Z

+The `#[used]` attribute can only be applied to `static` variables. This attribute forces the
+compiler to keep the variable in the output object file (.o, .rlib, etc.) even if the variable is
+not *used*, or referenced, by any other item in the crate. Without this attribute the compiler is
+free to remove variable if it's *unused*, or dead, when optimizations are enabled.


The language doesn't really have any guarantees about optimized vs. unoptimized behaviour. E.g., it wouldn't be a breaking change if we removed unused items from the binary in debug builds, AFAIK. As such, the "when optimizations are enabled" part should not be stated at all.

Havvy · 2018-06-20T22:43:20Z

+```
+
+``` console
+$ # with optimizations


Definitely should not show the differences between optimized and unoptimized here. A different compiler can make different choices here.

Havvy · 2018-06-20T22:45:55Z

@@ -0,0 +1,9 @@
+# Application Binary Interface (ABI)
+
+This section documents (or will document) features that affect the ABI of a Rust program / binary,


We avoid talking about future plans in the reference. Both the parentheticals here should be removed.

Havvy · 2018-06-20T22:46:20Z

+This section documents (or will document) features that affect the ABI of a Rust program / binary,
+rlib, dylib, etc. A (likely incomplete) list of such features is shown below:
+
+- #[used]


Should have code backticks for these.

Havvy · 2018-06-20T22:46:59Z

@@ -0,0 +1,62 @@
+## #[used]


There's no reason for this to have its own page. Or anything listed in the ABI section. I'd suggest merging the two pages.

japaric · 2018-06-22T02:41:41Z

@Havvy Thanks for the review. I think I have addressed all your comments in the last commit. Let me know if I missed something.

Havvy

Other than the nits and the whitespace thing, looks good to me.

Havvy · 2018-06-22T03:20:44Z

@@ -1,24 +1,24 @@
 # Attributes

-> **<sup>Syntax</sup>**


This whitespace is important. (I've made the same mistake before.)

Havvy · 2018-06-22T03:23:27Z

+#[used]
+static FOO: u32 = 0;
+
+// removed because it's unused


"removed" -> "removable"

Havvy · 2018-06-22T03:23:54Z

+ &QUUX
+}
+
+// removed because it's referenced by a private, unused (dead) function


"removed" -> "removable"

Havvy · 2018-06-22T03:24:50Z

+- `#[used]`
+- `extern "$ABI" fn`
+
+## `#[used]`


"The `used` attribute". Attribute names are just the name, not the attribute syntax with it.

Havvy · 2018-06-22T03:27:11Z

@@ -0,0 +1,60 @@
+# Application Binary Interface (ABI)
+
+This section documents features that affect the ABI of a Rust program / binary, rlib, dylib, etc. A


Still a slash here. We try to keep terminology precise in the reference, and the "program / binary" looks very imprecise.

steveklabnik · 2018-09-05T14:22:33Z

ping @japaric ! Are you able to update with the feedback?

Centril · 2019-01-10T18:56:16Z

ping @japaric -- any progress?

- Address review comments. - Add links to other parts of the reference. - Remove "list of features", will move these attributes in a future PR. - Remove feature(used), not needed. - Remove `pub` from QUUX. Otherwise it is the same as BAZ. I believe this was trying to illustrate that a private static accessed from a public function counts as "used".

ehuss · 2019-03-11T01:46:37Z

I have rebased this PR and addressed the review comments. I also made a few minor changes (explained in the last commit). I think it would be good to move the other attributes to the abi page later in a separate PR (export_name, link_section, and no_mangle).

Centril

Aside from the following nits, it LGTM.

done

Centril · 2019-03-11T04:28:13Z

@ehuss Merge when you are happy :)

Havvy · 2019-03-11T05:08:51Z

+#[allow(dead_code)]
+static BAR: u32 = 0;
+
+// This is kept because it is referenced by a public, reachable function:


This should be on QUUX, not BAZ. BAZ is kept because it is a public static.

Havvy · 2019-03-11T05:14:12Z

 object file that this item's contents will be placed into.
 - `no_mangle` - on any item, do not apply the standard name mangling. Set the
 symbol for this item to its identifier.
+- [`used`] - on statics, this forces the compiler to keep the variable in the


I don't like adding more attributes to the misc. attributes section. Could we rename Misc. attributes to "Object file attributes"? We could throw no_main, no_start and windows_subsystem in that heading too possibly (I really don't know much about object files...so taking a guess here). Where global_allocator goes, I don't know. Perchance just make it its own section?

I'm looking at regrouping and updating the attributes on the attributes page. I'd like to do that in a separate PR, if that's OK? I've opened issue #534 to discuss this further, I'd be happy if you could leave some feedback since you've done most of the initial work on this.

Havvy · 2019-03-11T19:58:50Z

💟 Thanks @japaric for getting this started and @ehuss for getting it finished.

Update books Update reference, book, rust-by-example, edition-guide, embedded-book ## reference 15 commits in 41493ff..27ad493 2019-03-05 12:32:22 +0100 to 2019-03-26 02:06:15 +0100 - Document wasm_import_module for #[link]. (rust-lang/reference#554) - Fix tidy error. (rust-lang/reference#552) - Some minor contributing updates. (rust-lang/reference#551) - Document `type_length_limit`. (rust-lang/reference#546) - Add some terms to the glossary. (rust-lang/reference#547) - Document `target_feature` and `cfg_target_feature`. (rust-lang/reference#545) - Remove undocumented page (rust-lang/reference#539) - Reorg and update attributes (rust-lang/reference#537) - Fix some minor link errors. (rust-lang/reference#538) - Add linkchecker. (rust-lang/reference#521) - Expand docs on Macros By Example. (rust-lang/reference#511) - document #[panic_handler] (rust-lang/reference#362) - document #[used] (rust-lang/reference#361) - Note that UB is program-global (rust-lang/reference#490) - Fix copy-paste error in procedural-macros.md (rust-lang/reference#533) ## book 16 commits in 9cffbeabec3bcec42d09432bfe7705125c848889..b93ec30bbc7b1b5c2f44223249ab359bed2ed5a6 2019-03-02 08:22:41 -0500 to 2019-03-26 16:54:10 -0400 - Unignore example that now compiles - Fix code snippet (rust-lang/book#1863) - Fix mdbook link text in readme (rust-lang/book#1881) - Wrap to 80 cols - Make sentence more complete (rust-lang/book#1885) - consistenly use increment and decrement (rust-lang/book#1884) - Fix link to Reference's conditional-compilation. (rust-lang/book#1878) - Fix subject/verb agreement - Remove nostarch snapshot files that have been incorporated and checked - haha teach the dictionary steve's name - Add authorship info to the front page - fix accidental <ol>'s (rust-lang/book#1866) - Edits to Macros (rust-lang/book#1848) - Mention `lock` returns `MutexGuard` wrapped in a `LockResult` - Add an example that illustrates NLL (rust-lang/book#1842) - change the parameter name from `type` to `kind` (rust-lang/book#1845) ## rust-by-example 33 commits in 2ce92beabb912d417a7314d6da83ac9b50dc2afb..f68ef3d0f4959f6a7d92a08d9994b117f0f4d32d 2018-11-20 10:10:23 -0500 to 2019-03-12 15:32:12 -0300 - Fix some broken links. (rust-lang/rust-by-example#1161) - Update links in README (rust-lang/rust-by-example#1167) - Add score/lifetimes/trait.md (rust-lang/rust-by-example#1168) - Fixrust-lang/rust-by-example#1147 - No more `open_mode` method (rust-lang/rust-by-example#1164) - Fix for loop description in list print example (rust-lang/rust-by-example#1162) - Add link to Cargo chapter in the index page (rust-lang/rust-by-example#1159) - Fix grammar in sentence about integer notation (rust-lang/rust-by-example#1157) - Do not use deprecated functions from `std::error::Error` trait (rust-lang/rust-by-example#1151) - Update new_types.md to clarify conversion to base type (rust-lang/rust-by-example#1148) - Fix compatibility with Rust 2018 (rust-lang/rust-by-example#1150) - Hello: Fix hint link in `fmt` chapter. (rust-lang/rust-by-example#1146) - Clarify pub(restricted) example a bit (rust-lang/rust-by-example#1133) - Add "literal" to list of macro designators (rust-lang/rust-by-example#1153) - Minor fixes for the macros chapter (rust-lang/rust-by-example#1113) - Use new book links instead of the old second-edition ones (rust-lang/rust-by-example#1143) - Recommend implementing Display over ToString (rust-lang/rust-by-example#1145) - Remove unused import and format with `rustfmt` (rust-lang/rust-by-example#1144) - fix typo (rust-lang/rust-by-example#1142) - Update syntax for 2018 Edition (rust-lang/rust-by-example#1136) - Added two missing full stops (rust-lang/rust-by-example#1138) - Removed unnecessary spaces before macro designators in macros/dry (rust-lang/rust-by-example#1139) - fix install mdbook command (rust-lang/rust-by-example#1128) - Changed word `function` to `type` in comment of fn area (rust-lang/rust-by-example#1132) - Added two missing backticks in generics/multi_bounds (rust-lang/rust-by-example#1129) - Fixed small logic error in error/option_unwrap/and_then (rust-lang/rust-by-example#1127) - Fix typo (rust-lang/rust-by-example#1125) - The code of conduct link was dead. I fixed it. (rust-lang/rust-by-example#1122) - I added a space in the Display fmt for Complex (rust-lang/rust-by-example#1123) - Fix Rust install link in the index (rust-lang/rust-by-example#1124) - Update cargo conventions section (rust-lang/rust-by-example#1121) - Fixed curly braces in the `To and from Strings` chapter to be parentheses (rust-lang/rust-by-example#1120) - Edit a typo (rust-lang/rust-by-example#1119) - Fixesrust-lang/rust-by-example#1115 by correcting the typo from into_iterator to into_iter (rust-lang/rust-by-example#1118) ## edition-guide 1 commits in aa0022c875907886cae8f3ef8e9ebf6e2a5e728d..b56ddb11548450a6df4edd1ed571b2bc304eb9e6 2019-02-27 22:10:39 -0800 to 2019-03-10 10:23:16 +0100 - Links fixes (rust-lang/edition-guide#133) ## embedded-book 6 commits in 9e656ead82bfe869493dec82653a52e27fa6a05c..07fd3880ea0874d82b1d9ed30ad3427ec98b4e8a 2019-03-03 16:03:26 +0000 to 2019-03-27 15:40:52 +0000 - Fix test errors. (rust-embedded/book#180) - Update qemu.md (rust-embedded/book#170) - Update no-std.md to remove obsolete FAQ link (rust-embedded/book#177) - We've come a long way :) (rust-embedded/book#176) - Correct link to team (rust-embedded/book#175) - Update some book links to their new homes. (rust-embedded/book#173)

japaric mentioned this pull request Jun 20, 2018
stabilize #[used] rust-lang/rust#51363
Merged

Havvy suggested changes Jun 20, 2018
View reviewed changes

Havvy previously requested changes Jun 22, 2018
View reviewed changes

Havvy added the RFC Stabilization Docs Documentation required for stabilizing a feature label Jun 22, 2018

alercah assigned alercah and japaric and unassigned alercah Aug 3, 2018

ehuss mentioned this pull request Mar 8, 2019
Undocumented Attributes #532
Closed
6 tasks

japaricand others added 3 commits March 10, 2019 17:54

document #[used]
26d49a1

address review comments
e47b299

ehuss force-pushed the used branch from ddccd12 to 9fd5b4dCompare March 11, 2019 01:43

Centril reviewed Mar 11, 2019
View reviewed changes

Comment threadsrc/attributes.md Outdated
Comment threadsrc/abi.md Outdated
Comment threadsrc/abi.md Outdated
Comment threadsrc/abi.md Outdated
Comment threadsrc/abi.md Outdated
Comment threadsrc/abi.md Outdated
Comment threadsrc/abi.md Outdated
Comment threadsrc/abi.md Outdated

Update for centril's review.
a2f10c4

Centril approved these changes Mar 11, 2019
View reviewed changes

Havvy reviewed Mar 11, 2019
View reviewed changes

Fix comment error.
c31b4fa

Havvy approved these changes Mar 11, 2019
View reviewed changes

Havvy merged commit 2f9a1f2 into rust-lang:masterMar 11, 2019

ehuss mentioned this pull request Mar 22, 2019
Update books rust-lang/rust#59366
Merged

		@@ -0,0 +1,9 @@
		# Application Binary Interface (ABI)

		This section documents (or will document) features that affect the ABI of a Rust program / binary,

		@@ -0,0 +1,60 @@
		# Application Binary Interface (ABI)

		This section documents features that affect the ABI of a Rust program / binary, rlib, dylib, etc. A

Uh oh!

Conversation

japaric commented Jun 20, 2018

Uh oh!

steveklabnik commented Jun 20, 2018

Uh oh!

Havvy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

japaric commented Jun 22, 2018

Uh oh!

Havvy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

steveklabnik commented Sep 5, 2018

Uh oh!

Centril commented Jan 10, 2019

Uh oh!

ehuss commented Mar 11, 2019

Uh oh!

Centril left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Centril commented Mar 11, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Havvy commented Mar 11, 2019

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants