First stab at documenting RakuAST::Doc::Declarator

Author: lizmat

doc/Type/RakuAST/Doc/Declarator.rakudoc

@@ -0,0 +1,137 @@
+=begin pod :kind("Type") :subkind("class") :category("basic")
+
+=TITLE class RakuAST::Doc::Declarator
+
+=SUBTITLE 
+
+    class RakuAST::Doc::Declarator { }
+
+The C<RakuAST::Doc::Declarator> class contains the leading and trailing
+documentation of an object doing the C<RakuAST::Doc::DeclaratorTarget>
+role.
+
+Support for C<RakuAST> functionality is available in language version
+C<6.e+> and was added in Rakudo compiler release 2023.02.  In earlier
+language versions it is only available when specifying:
+
+    use experimental :rakuast;
+
+=head2 Object introspection
+
+C<RakuAST::Doc::Declarator> objects are typically created when parsing
+Raku Programming Language code that has objects with leading (C<#|>)
+and trailing (C<#=>) documentation on it.  So most developers will only
+need to know how to introspect the objects created.
+
+=head3 method WHEREFORE
+
+    say "attached to a $declarator.WHEREFORE.^name() object";
+
+Returns the object for which this object contains the declarator
+documentation.
+
+=head3 method leading
+
+    .say for $declarator.leading;
+
+Returns the lines of the leading declarator documentation (one
+for each line with C<#|> if the object was created from parsing
+Raku source code.
+
+=head3 method trailing
+
+    .say for $declarator.trailing;
+
+Returns the lines of the trailing declarator documentation (one
+for each line with C<#=> if the object was created from parsing
+Raku source code.
+
+=head3 method raku
+
+   # method .gist falls back to .raku
+   say $declarator;  # RakuAST::Doc::Declarator.new(...
+
+Returns the string that is needed for the creation of the block
+using C<RakuAST> calls.
+
+=head1 Object creation
+
+One seldomly creates C<RakuAST::Doc::Declarator> objects directly.  This
+documentation is intended for those few people who'd like to devise
+their own way of programmatically building a C<RakuAST::Doc::Declarator>
+object.
+
+=head2 method new
+
+    method new(
+      Str:D :$WHEREFORE,  # the associated RakuAST object
+            :@leading,    # leading lines of documentation
+            :@trailing    # trailing lines of documentation
+    );
+
+The C<new> method can be called to create a new C<RakuAST::Doc::Declarator>
+object.  It only takes named arguments.
+
+=begin code :lang<raku>
+# there is no syntax for creating just a ::Declarator object
+
+my $declarator = RakuAST::Doc::Declarator.new(
+  :WHEREFORE(RakuAST::VarDeclaration::Simple.new(...),
+  :leading("line 1 leading","line 2 leading"),
+  :trailing("line 1 trailing","line 2 trailing")
+);
+=end code
+
+Note that the leading and trailing documentation may contain any
+left margin whitespace.
+
+=head3 :WHEREFORE
+
+The C<RakuAST> object for which this declarator contains the documentation.
+
+=head3 :leading
+
+A C<Positional> with the lines of leading documentation strings.
+
+=head3 :trailing
+
+A C<Positional> with the lines of trailing documentation strings.
+
+=head1 Object modification
+
+=head2 method set-WHEREFORE
+
+    $declarator.set-WHEREFORE($object);
+
+Set the object for which the C<RakuAST::Doc::Declarator> object contains
+the documentation.
+
+=head2 method set-leading
+
+    $declarator.set-leading;  # reset
+    $declarator.set-leading("foo", "bar");
+
+Set the leading documentation.  If no arguments are specified, reset to
+not having any leading documentation.
+
+=head2 method add-leading
+
+    $declarator.add-leading("additional");
+
+Add a line to the leading documentation.
+
+=head2 method set-trailing
+
+    $declarator.set-trailing;  # reset
+    $declarator.set-trailing("foo", "bar");
+
+Set the trailing documentation.  If no arguments are specified, reset to
+not having any trailing documentation.
+
+=head2 method add-trailing
+
+    $declarator.add-trailing("additional");
+
+Add a line to the trailing documentation.
+
+=end pod