Improve &find-definitions documentation a bit

Author: Mouq

htmlify.p6

@@ -304,17 +304,19 @@ multi write-type-source($doc) {
     spurt "html/$what/$podname.html", p2h($pod, $what);
 }
 
+#| A one-pass-parser for pod headers that define something documentable.
 sub find-definitions (:$pod, :$origin, :$min-level = -1) {
-    # Run through the pod content, and look for headings.
-    # If a heading is a definition, like "class FooBar", process
-    # the class and give the rest of the pod to find-definitions,
+    # Runs through the pod content, and looks for headings.
+    # If a heading is a definition, like "class FooBar", processes
+    # the class and gives the rest of the pod to find-definitions,
     # which will return how far the definition of "class FooBar" extends.
-    my @all-pod-elements := $pod ~~ Positional ?? @$pod !! $pod.contents;
+    # We then continue parsing from after that point.
+    my @pod-section := $pod ~~ Positional ?? @$pod !! $pod.contents;
     my int $i = 0;
-    my int $len = +@all-pod-elements;
+    my int $len = +@pod-section;
     while $i < $len {
         NEXT {$i = $i + 1}
-        my $pod-element := @all-pod-elements[$i];
+        my $pod-element := @pod-section[$i];
         next unless $pod-element ~~ Pod::Heading;
         return $i if $pod-element.level <= $min-level;
 
@@ -368,8 +370,8 @@ sub find-definitions (:$pod, :$origin, :$min-level = -1) {
                 }
                 when 'class'|'role'|'enum' {
                     my $summary = '';
-                    if @all-pod-elements[$i+1] ~~ {$_ ~~ Pod::Block::Named and .name eq "SUBTITLE"} {
-                        $summary = @all-pod-elements[$i+1].contents[0].contents[0];
+                    if @pod-section[$i+1] ~~ {$_ ~~ Pod::Block::Named and .name eq "SUBTITLE"} {
+                        $summary = @pod-section[$i+1].contents[0].contents[0];
                     } else {
                         note "$name does not have an =SUBTITLE";
                     }
@@ -407,18 +409,18 @@ sub find-definitions (:$pod, :$origin, :$min-level = -1) {
             # And updating $i to be after the places we've already searched
             once {
                 $new-i = $i + find-definitions
-                    :pod(@all-pod-elements[$i+1..*]),
+                    :pod(@pod-section[$i+1..*]),
                     :origin($created),
-                    :min-level(@all-pod-elements[$i].level);
+                    :min-level(@pod-section[$i].level);
             }
 
             my $new-head = Pod::Heading.new(
-                :level(@all-pod-elements[$i].level),
+                :level(@pod-section[$i].level),
                 :contents[pod-link "$subkinds $name",
                     $created.url ~ "#$origin.human-kind() $origin.name()".subst(:g, /\s+/, '_')
                 ]
             );
-            my @orig-chunk = $new-head, @all-pod-elements[$i ^.. $new-i];
+            my @orig-chunk = $new-head, @pod-section[$i ^.. $new-i];
             my $chunk = $created.pod.push: pod-lower-headings(@orig-chunk, :to(%attr<kind> eq 'type' ?? 0 !! 2));
 
             if $subkinds eq 'routine' {