Add test for <> (missing formatcode) (#4257)

* Add test for <> (missing formatcode)
* Fixup some missing C<> in pod.

doc/Language/101-basics.rakudoc

@@ -416,7 +416,7 @@ Let's see an example of this now.
 In this example, you will see some special syntax that makes it easier
 to make a list of strings. This is the
 C«<...>» L<quote-words|/language/operators#index-entry-qw-quote-words-quote-words>
-construct. When you put words in between the < and > they are all assumed
+construct. When you put words in between the C«<» and C«>» they are all assumed
 to be strings, so you do not need to wrap them each in double quotes
 C«"..."».
 

doc/Language/5to6-nutshell.rakudoc

@@ -1108,7 +1108,7 @@ ago and may lack features that have been added since the beginning of the
 Raku project. Two such features not yet implemented in Raku for the P5
 syntax are the Perl Unicode property matchers C<\p{}> and C<\P{}>.
 
-=head2 Special matchers generally fall under the <> syntax
+=head2 Special matchers generally fall under the C«<>» syntax
 
 There are many cases of special matching syntax that Perl regexes
 support. They won't all be listed here but often, instead of being

doc/Language/5to6-perlvar.rakudoc

@@ -216,7 +216,7 @@ The C<Str> method on all of the above produces the I<short> version of the infor
 at the current time the C<name>.
 
 All the objects have other methods that can be useful when trying to identify the
-exact running instance, for more information use <.^methods> to introspect all the above.
+exact running instance, for more information use C<.^methods> to introspect all the above.
 
 =head3 %SIG
 

doc/Language/js-nutshell.rakudoc

@@ -99,6 +99,7 @@ constant foo = 1; # Package scoped; constant
 my  $*foo = 1; # Dynamic variable; lexically scoped
 our $*foo = 1; # Dynamic variable; package scoped
 
+=for code
 GLOBAL::<$foo> := 1; # Globally scoped
 
 Use C<my> where you'd use C<let>, C<our> for variables you'd define in the

doc/Language/modules.rakudoc

@@ -1063,7 +1063,7 @@ fez register
 
 =item Now you can upload your module!
 
-Before doing the following, ensure your C<META6.json> file's "auth" matches "zef:<username>" and then:
+Before doing the following, ensure your C<META6.json> file's C<auth> matches C«zef:<username>» and then:
 
 =begin code :lang<shell>
 fez upload

doc/Language/quoting.rakudoc

@@ -355,7 +355,7 @@ It's easier to write and to read this:
 
     my @directions = qw|left right up down|;
 
-=head2 Word quoting: < >
+=head2 Word quoting: C«< >»
 X«|Syntax,< > word quote»
 
 =for code :allow<B L>

doc/Language/regexes.rakudoc

@@ -2388,7 +2388,7 @@ C«<.ws>» subrule calls depending on where it occurs in the regex.
     =end code
 
 C<m:s/ photo shop /> acts the same as
-C<m/ photo <.ws> shop <.ws> />. By default, C«<.ws>» makes sure that
+C<m/ photo C«<.ws>» shop <.ws> />. By default, C«<.ws>» makes sure that
 words are separated, so C<a    b> and C<^&> will match C«<.ws>» in the
 middle, but C<ab> won't:
 

doc/Type/CX/Done.rakudoc

@@ -15,6 +15,6 @@ indicate a supply block is finished by calling C<done>.
 
     method message()
 
-Returns "<done control exception>"
+Returns C<'<done control exception>'>.
 
 =end pod

doc/Type/CX/Emit.rakudoc

@@ -15,6 +15,6 @@ emit is used inside a C<Supply> block.
 
     method message()
 
-Returns "<emit control exception>"
+Returns C<'<emit control exception>'>.
 
 =end pod

doc/Type/CX/Last.rakudoc

@@ -15,7 +15,7 @@ when C<last> is called.
 
     method message()
 
-Returns "<last control exception>". Since this type of exception is to be
+Returns C<'<last control exception>'>. Since this type of exception is to be
 consumed by type and not really by the content of the message, this is a generic
 message, similar to all other C<CX::*> exceptions.
 

doc/Type/CX/Next.rakudoc

@@ -39,6 +39,6 @@ We're in 9
 
     method message()
 
-Returns "<next control exception>"
+Returns C<'<next control exception>'>.
 
 =end pod

doc/Type/CX/Proceed.rakudoc

@@ -15,6 +15,6 @@ C<proceed> is used within C<when> or C<default> blocks.
 
     method message()
 
-Returns "<proceed control exception>"
+Returns C<'<proceed control exception>'>.
 
 =end pod

doc/Type/CX/Redo.rakudoc

@@ -15,6 +15,6 @@ C<redo> is called.
 
     method message()
 
-Returns "<redo control exception>".
+Returns C<'<redo control exception>'>.
 
 =end pod

doc/Type/CX/Return.rakudoc

@@ -15,6 +15,6 @@ return is called from within a sub.
 
     method message()
 
-Returns "<return control exception>"
+Returns C<'<return control exception>'>.
 
 =end pod

doc/Type/CX/Succeed.rakudoc

@@ -15,6 +15,6 @@ C<succeed> is called from a C<when> or C<default> block.
 
     method message()
 
-Returns "<next control exception>"
+Returns C<'<next control exception>'>.
 
 =end pod

doc/Type/CX/Take.rakudoc

@@ -15,6 +15,6 @@ C<take>.
 
     method message()
 
-Returns "<take control exception>".
+Returns C<'<take control exception>'>.
 
 =end pod

doc/Type/CX/Warn.rakudoc

@@ -15,5 +15,4 @@ incidence.
 
 C<CX::Warn> objects are created when a warning is thrown in any block.
 
-
 =end pod

doc/Type/Thread.rakudoc

@@ -109,7 +109,7 @@ the thread will be killed when the main thread of the process terminates.
     method name(Thread:D: --> Str:D)
 
 Returns the user defined string, which can optionally be set during object
-creation in order to identify the C<Thread>, or '<anon>' if no such string
+creation in order to identify the C<Thread>, or C<'<anon>'> if no such string
 was specified.
 
     my $t1 = Thread.new(code => { for 1..5 -> $v { say $v }});

doc/Type/X/Method/InvalidQualifier.rakudoc

@@ -7,7 +7,7 @@
     class X::Method::InvalidQualifier is Exception { }
 
 Thrown when a method is call in the form C<$invocant.TheClass::method> if
-<$invocant> does not conform to C<TheClass>.
+C<$invocant> does not conform to C<TheClass>.
 
 For example
 

xt/rakudoc-brackets.rakutest

@@ -0,0 +1,62 @@
+#!/usr/bin/env raku
+
+=begin overview
+
+It's possible for users to forget to add a formatting code when
+wrapping something in angle brackets:
+
+    This was supposed to be <bold>.
+
+This is valid pod, but in practices, these dangling <>'s often indicate an error.
+Complain whenever we find them, except for infix:<> and prefix:<>
+
+=end overview
+
+use Test;
+use lib $*PROGRAM.parent(2).child('lib');
+
+use Test-Files;
+use Pod::Convenience;
+
+my @files = Test-Files.pods;
+
+if @files {
+    plan +@files;
+} else {
+    plan :skip-all<No rakudoc files specified>
+}
+
+sub is-valid-text($node) {
+    # Should be ok to look at only literal strings that get passed
+    if $node ~~ Str {
+        if $node ~~ / $<bracketed>=['<' .*? '>'] / {
+            return if ~$/<bracketed>.contains("prefix:<" | "infix:<" );
+            flunk ~$/<bracketed> ~ " is likely missing a formatting code";
+        }
+    }
+
+}
+
+sub walk-content($item) {
+    if !(
+        $item ~~ Pod::Block::Code or
+        $item ~~ Pod::Block::Comment or
+        $item ~~ Pod::FormattingCode
+    ) {
+        is-valid-text($item);
+        next unless $item.can('contents');
+        for @($item.contents) -> $child {
+            walk-content($child);
+        }
+    }
+}
+
+# Walk through pod on each file.
+for @files -> $file {
+    my @chunks = extract-pod($file).contents;
+
+    # This emits pass or flunk for each local L<> found.
+    subtest $file => {
+        walk-content($_) for @chunks;
+    }
+}