Add some comments to help clarify some features stuff from review.

Author: ehuss

src/cargo/core/compiler/unit_dependencies.rs

@@ -287,8 +287,15 @@ fn compute_deps<'a, 'cfg>(
         };
         let mode = check_or_build_mode(unit.mode, lib);
         let dep_kind = if unit.target.is_custom_build() {
+            // Custom build scripts can *only* have build-dependencies.
             DepKind::Build
         } else if deps.iter().any(|dep| !dep.is_transitive()) {
+            // A dependency can be listed in both [dependencies] and
+            // [dev-dependencies], so this checks if any of the deps are
+            // listed in dev-dependencies. Note that `filtered_deps` has
+            // already removed dev-dependencies if it is not a
+            // test/bench/example, so it is not necessary to check `unit`
+            // here.
             DepKind::Development
         } else {
             DepKind::Normal

src/cargo/core/resolver/features.rs

@@ -25,6 +25,14 @@ use crate::util::{CargoResult, Config};
 use std::collections::{BTreeSet, HashMap, HashSet};
 use std::rc::Rc;
 
+/// Map of activated features for a PackageId/DepKind/CompileKind.
+///
+/// `DepKind` is needed, as the same package can be built multiple times with
+/// different features. For example, with `decouple_build_deps`, a dependency
+/// can be built once as a build dependency (for example with a 'std'
+/// feature), and once as a normal dependency (without that 'std' feature).
+///
+/// `CompileKind` is used currently not needed.
 type ActivateMap = HashMap<(PackageId, DepKind, CompileKind), BTreeSet<InternedString>>;
 
 /// Set of all activated features for all packages in the resolve graph.

src/cargo/ops/cargo_compile.rs

@@ -746,6 +746,9 @@ fn generate_targets<'a>(
             bcx.profiles
                 .get_profile(pkg.package_id(), ws.is_member(pkg), unit_for, target_mode);
 
+        // Root units are not a dependency of anything, so they are always
+        // DepKind::Normal. Their features are driven by the command-line
+        // arguments.
         let features = Vec::from(resolved_features.activated_features(
             pkg.package_id(),
             DepKind::Normal,
@@ -934,6 +937,11 @@ fn generate_targets<'a>(
     Ok(units.into_iter().collect())
 }
 
+/// Gets all of the features enabled for a package, plus its dependencies'
+/// features.
+///
+/// Dependencies are added as `dep_name/feat_name` because `required-features`
+/// wants to support that syntax.
 fn resolve_all_features(
     resolve_with_overrides: &Resolve,
     resolved_features: &features::ResolvedFeatures,