Update comments in Cargo.toml

Cargo.toml

@@ -23,19 +23,22 @@ cfg-if = "0.1.10"
 rustc-demangle = "0.1.4"
 backtrace-sys = { path = "crates/backtrace-sys", version = "0.1.35", optional = true, default_features = false }
 libc = { version = "0.2.45", default-features = false }
-core = { version = "1.0.0", optional = true, package = 'rustc-std-workspace-core' }
-compiler_builtins = { version = '0.1.2', optional = true }
 
-# Optionally enable the ability to serialize a `Backtrace`
+# Optionally enable the ability to serialize a `Backtrace`, controlled through
+# the `serialize-*` features below.
 serde = { version = "1.0", optional = true, features = ['derive'] }
 rustc-serialize = { version = "0.3", optional = true }
 
 # Optionally demangle C++ frames' symbols in backtraces.
 cpp_demangle = { default-features = false, version = "0.2.3", optional = true }
 
-# Optional dependencies enabled through the `gimli-symbolize` feature
-addr2line = { version = "0.12.0", optional = true, default-features = false }
+# Internal dependencies when built as a dependency of libstd, do not use.
+core = { version = "1.0.0", optional = true, package = 'rustc-std-workspace-core' }
+compiler_builtins = { version = '0.1.2', optional = true }
 
+# Optional dependencies enabled through the `gimli-symbolize` feature, do not
+# use these features directly.
+addr2line = { version = "0.12.0", optional = true, default-features = false }
 [dependencies.object]
 version = "0.19"
 optional = true
@@ -45,34 +48,24 @@ features = ['read_core', 'elf', 'macho', 'pe']
 [target.'cfg(windows)'.dependencies]
 winapi = { version = "0.3.3", optional = true }
 
-# Each feature controls the two phases of finding a backtrace: getting a
-# backtrace and then resolving instruction pointers to symbols. The default
-# feature enables all the necessary features for each platform this library
-# supports, but it can be disabled to have finer grained control over the
-# dependencies.
-#
-# Note that not all features are available on all platforms, so even though a
-# feature is enabled some other feature may be used instead.
 [features]
+# By default libstd support and libbacktrace is used to symbolize addresses.
 default = ["std", "libbacktrace"]
 
-# Include std support.
+# Include std support. This enables types like `Backtrace`.
 std = []
 
 #=======================================
 # Methods of resolving symbols
 #
 # - libbacktrace: this feature activates the `backtrace-sys` dependency,
-#   building the libbacktrace library found in gcc repos. This library
-#   parses the DWARF info of ELF executables to find symbol names, and it
-#   can also provide filename/line number information if debuginfo is
-#   compiled in. This library currently only primarily works on unixes that
-#   are not OSX, however.
+#   building the libbacktrace library found in gcc repos. This is the historical
+#   default for the `backtrace` crate.
 # - gimli-symbolize: use the `gimli-rs/addr2line` crate to symbolicate
-#   addresses into file, line, and name using DWARF debug information. At
-#   the moment, this is only possible when targetting Linux, since macOS
-#   splits DWARF out into a separate object file. Enabling this feature
-#   means one less C dependency.
+#   addresses into file, line, and name using DWARF debug information.
+#
+# Note that MSVC unconditionally uses the dbghelp library to symbolize and won't
+# be affected by feature selection here.
 libbacktrace = ["backtrace-sys/backtrace-sys"]
 gimli-symbolize = ["addr2line", "object", "std"]
 
@@ -84,18 +77,16 @@ serialize-rustc = ["rustc-serialize"]
 serialize-serde = ["serde"]
 
 #=======================================
-# Deprecated features
+# Deprecated/internal features
 #
-# Only here for backwards compatibility purposes, they do nothing now.
+# Only here for backwards compatibility purposes or for internal testing
+# purposes. New code should use none of these features.
 coresymbolication = []
 dladdr = []
 kernel32 = []
 unix-backtrace = []
 libunwind = []
 dbghelp = []
-
-#=======================================
-# Internal features for testing and such.
 verify-winapi = [
   'winapi/dbghelp',
   'winapi/handleapi',