Improve documentation of slices rules (#1454)

codecholeric · web-flow · commit 4b536129e584 · 2025-05-07T21:35:53.000+02:00
[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())
diff --git a/archunit/src/main/java/com/tngtech/archunit/library/dependencies/SlicesRuleDefinition.java b/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)
diff --git a/archunit/src/main/java/com/tngtech/archunit/library/dependencies/syntax/SlicesShould.java b/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();
 }
diff --git a/docs/userguide/008_The_Library_API.adoc b/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
diff --git a/docs/userguide/html/000_Index.html b/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
