Improve documentation of slices rules (#1454)

[The user guide's slices
documentation](https://www.archunit.org/userguide/html/000_Index.html#_slices)
had a comment that didn't perfectly match the code:
```java
// checks all subpackages of 'myapp' for cycles
SlicesRuleDefinition.slices().matching("..myapp.(**)").should().notDependOnEachOther()
```

In addition, the involved methods could use some more JavaDoc:
*
[`matching(String)`](https://javadoc.io/static/com.tngtech.archunit/archunit/1.4.0/com/tngtech/archunit/library/dependencies/SlicesRuleDefinition.Creator.html#matching(java.lang.String))
*
[`notDependOnEachOther()`](https://javadoc.io/static/com.tngtech.archunit/archunit/1.4.0/com/tngtech/archunit/library/dependencies/syntax/SlicesShould.html#notDependOnEachOther())

Author: codecholeric

archunit/src/main/java/com/tngtech/archunit/library/dependencies/SlicesRuleDefinition.java

@@ -16,6 +16,7 @@
 package com.tngtech.archunit.library.dependencies;
 
 import com.tngtech.archunit.PublicAPI;
+import com.tngtech.archunit.core.domain.PackageMatcher;
 import com.tngtech.archunit.lang.ArchRule;
 import com.tngtech.archunit.lang.Priority;
 import com.tngtech.archunit.library.dependencies.syntax.GivenSlices;
@@ -24,22 +25,20 @@
 import static com.tngtech.archunit.PublicAPI.Usage.ACCESS;
 
 /**
- * Allows to specify {@link ArchRule ArchRules} for "slices" of a code base. A slice is conceptually
- * a cut through a code base according to business logic. Take for example
+ * Allows to specify {@link ArchRule ArchRules} for "slices" of a code base.
+ * A slice is conceptually a cut through a code base according to business logic.
+ * <h6>Example</h6>
  * <pre><code>
  * com.mycompany.myapp.order
  * com.mycompany.myapp.customer
  * com.mycompany.myapp.user
  * com.mycompany.myapp.authorization
  * </code></pre>
- * The top level packages under 'myapp' are composed according to different domain aspects. It is
- * good practice, to keep such packages free of cycles, which is one capability that this class
- * provides.<br>
- * Consider
- * <pre><code>
- * {@link #slices() slices()}.{@link Slices#matching(String) matching("..myapp.(*)..")}.{@link GivenSlices#should() should()}.{@link SlicesShould#beFreeOfCycles() beFreeOfCycles()}
- * </code></pre>
- * Then this rule will assert, that the four slices of 'myapp' are free of cycles.
+ * The top level packages under {@code myapp} are composed according to different domain aspects.
+ * It is good practice to keep such packages free of cycles,
+ * which can be tested with the following rule:
+ * <pre><code>{@link #slices() slices()}.{@link Creator#matching(String) matching("..myapp.(*)..")}.{@link GivenSlices#should() should()}.{@link SlicesShould#beFreeOfCycles() beFreeOfCycles()}</code></pre>
+ * This rule asserts that the four slices of {@code myapp} are free of cycles.
  */
 @PublicAPI(usage = ACCESS)
 public final class SlicesRuleDefinition {
@@ -60,6 +59,8 @@ private Creator() {
         }
 
         /**
+         * defines a {@link SlicesRuleDefinition "slices" rule}
+         * based on a {@link PackageMatcher package identifier} with capturing groups
          * @see Slices#matching(String)
          */
         @PublicAPI(usage = ACCESS)
@@ -68,6 +69,8 @@ public GivenSlices matching(String packageIdentifier) {
         }
 
         /**
+         * defines a {@link SlicesRuleDefinition "slices" rule}
+         * based on a {@link PackageMatcher package identifier} with capturing groups
          * @see Slices#matching(String)
          */
         @PublicAPI(usage = ACCESS)
@@ -76,6 +79,8 @@ public GivenSlices matching(String packageIdentifier, Priority priority) {
         }
 
         /**
+         * defines a {@link SlicesRuleDefinition "slices" rule}
+         * based on an explicit {@link SliceAssignment}
          * @see Slices#assignedFrom(SliceAssignment)
          */
         @PublicAPI(usage = ACCESS)
@@ -84,6 +89,8 @@ public GivenSlices assignedFrom(SliceAssignment assignment) {
         }
 
         /**
+         * defines a {@link SlicesRuleDefinition "slices" rule}
+         * based on an explicit {@link SliceAssignment}
          * @see Slices#assignedFrom(SliceAssignment)
          */
         @PublicAPI(usage = ACCESS)

archunit/src/main/java/com/tngtech/archunit/library/dependencies/syntax/SlicesShould.java

@@ -22,9 +22,21 @@
 
 @PublicAPI(usage = ACCESS)
 public interface SlicesShould {
+    /**
+     * @return a {@link SliceRule} asserting that
+     * there are no cycles via dependencies between the evaluated slices
+     * (which is weaker than requiring
+     * that the slices do {@link #notDependOnEachOther()} at all)
+     */
     @PublicAPI(usage = ACCESS)
     SliceRule beFreeOfCycles();
 
+    /**
+     * @return a {@link SliceRule} asserting that
+     * there are no dependencies at all between the evaluated slices
+     * (which is stronger than requiring
+     * that {@link #beFreeOfCycles() there are no dependency cycles} between the slices)
+     */
     @PublicAPI(usage = ACCESS)
     SliceRule notDependOnEachOther();
 }

docs/userguide/008_The_Library_API.adoc

@@ -139,7 +139,7 @@ infixes, and then write assertions against those slices. At the moment this is f
 SlicesRuleDefinition.slices().matching("..myapp.(*)..").should().beFreeOfCycles()
 
 // checks all subpackages of 'myapp' for cycles
-SlicesRuleDefinition.slices().matching("..myapp.(**)").should().notDependOnEachOther()
+SlicesRuleDefinition.slices().matching("..myapp.(**)").should().beFreeOfCycles()
 
 // sort classes by packages between 'myapp' and 'service'
 // then check those slices for not having any dependencies on each other

docs/userguide/html/000_Index.html

@@ -1813,7 +1813,7 @@ <h3 id="_slices"><a class="anchor" href="#_slices"></a>8.2. Slices</h3>
 SlicesRuleDefinition.slices().matching("..myapp.(*)..").should().beFreeOfCycles()
 
 // checks all subpackages of 'myapp' for cycles
-SlicesRuleDefinition.slices().matching("..myapp.(**)").should().notDependOnEachOther()
+SlicesRuleDefinition.slices().matching("..myapp.(**)").should().beFreeOfCycles()
 
 // sort classes by packages between 'myapp' and 'service'
 // then check those slices for not having any dependencies on each other