gnodet commented on code in PR #2039:
URL: https://github.com/apache/maven-resolver/pull/2039#discussion_r3721418732
##
src/site/markdown/dependency-graph.md:
##
@@ -51,32 +51,26 @@ a:1 b:1
c:1
```
-The dependency tree is a handy data structure to get the complete set of
-artifacts one would need to form a classpath etc. as a simple recursive
-traversal is sufficient to gather the relevant dependencies.
+The dependency tree is a useful data structure.
+It provides the complete set of artifacts that are necessary to form a
classpath.
+A simple recursive traversal gathers the relevant dependencies.
## Troubleshooting a Dependency Graph
-The dependency tree provides a compact and basic means to end users to
-understand why/how a given artifact ended up among the dependencies. But
-as the examples above illustrate, the dependency tree misses some
-information compared to the dependency graph. For instance, the tree
-does not indicate that `b:1` also depends on `c:1`. To help
-troubleshooting complex dependency graphs, some configuration properties
-exist to keep useful data in the dependency graph returned by
-`RepositorySystem.collectDependencies()`.
+The dependency tree provides a basic way for end users to understand why and
how a given artifact became a dependency.
+But the dependency tree misses some information that the dependency graph has.
+The examples above illustrate this.
+For example, the tree does not show that `b:1` also depends on `c:1`.
+To troubleshoot complex dependency graphs, some configuration properties keep
useful data in the dependency graph returned by
`RepositorySystem.collectDependencies()`.
-For instance, the configuration property
-`ConflictResolver.CONFIG_PROP_VERBOSE` can be enabled to produce a graph
-similar to m2e's dependency hierarchy view where conflicting nodes are
-retained. This gives end users a better understanding of all the paths
-that pull in a given dependency.
+For example, the configuration property `ConflictResolver.CONFIG_PROP_VERBOSE`
can produce a graph similar to the dependency hierarchy view in m2e.
Review Comment:
"can be enabled to produce" was shortened to "can produce" — this drops the
signal that `ConflictResolver.CONFIG_PROP_VERBOSE` is disabled by default and
must be explicitly enabled. An STE-compliant imperative construction would
preserve both the style and the opt-in semantics:
```suggestion
For example, enable the configuration property
`ConflictResolver.CONFIG_PROP_VERBOSE` to produce a graph similar to the
dependency hierarchy view in m2e.
```
##
src/site/markdown/dependency-graph.md:
##
@@ -51,32 +51,26 @@ a:1 b:1
c:1
```
-The dependency tree is a handy data structure to get the complete set of
-artifacts one would need to form a classpath etc. as a simple recursive
-traversal is sufficient to gather the relevant dependencies.
+The dependency tree is a useful data structure.
+It provides the complete set of artifacts that are necessary to form a
classpath.
+A simple recursive traversal gathers the relevant dependencies.
## Troubleshooting a Dependency Graph
-The dependency tree provides a compact and basic means to end users to
-understand why/how a given artifact ended up among the dependencies. But
-as the examples above illustrate, the dependency tree misses some
-information compared to the dependency graph. For instance, the tree
-does not indicate that `b:1` also depends on `c:1`. To help
-troubleshooting complex dependency graphs, some configuration properties
-exist to keep useful data in the dependency graph returned by
-`RepositorySystem.collectDependencies()`.
+The dependency tree provides a basic way for end users to understand why and
how a given artifact became a dependency.
+But the dependency tree misses some information that the dependency graph has.
+The examples above illustrate this.
+For example, the tree does not show that `b:1` also depends on `c:1`.
+To troubleshoot complex dependency graphs, some configuration properties keep
useful data in the dependency graph returned by
`RepositorySystem.collectDependencies()`.
-For instance, the configuration property
-`ConflictResolver.CONFIG_PROP_VERBOSE` can be enabled to produce a graph
-similar to m2e's dependency hierarchy view where conflicting nodes are
-retained. This gives end users a better understanding of all the paths
-that pull in a given dependency.
+For example, the configuration property `ConflictResolver.CONFIG_PROP_VERBOSE`
can produce a graph similar to the dependency hierarchy view in m2e.
+The graph keeps the nodes that conflict.
+This helps end users understand all the paths that pull in a given dependency.
-The configuration property `DependencyManagerUtils.CONFIG_PROP_VERBOSE`
-can be enabled to record the attributes of a dependency before they were
-updated due to dependency management. This helps end users to understand
-why one version of a dependency
