txt: ## declarator.md
  class RakuAST::Doc::Declarator
  
  Contains the declarator docs of a RakuAST object
  
  ```raku
  class RakuAST::Doc::Declarator { }
  ```
  
  The `RakuAST::Doc::Declarator` class contains the leading and trailing documentation of an object doing the [`RakuAST::Doc::DeclaratorTarget`](/type/RakuAST/Doc/DeclaratorTarget) role.
  
  Support for [`RakuAST`](/type/RakuAST) functionality is available in language version `6.e+` and was added in Rakudo compiler release 2023.02. In earlier language versions it is only available when specifying:
  
  ```raku
  use experimental :rakuast;
  ```
  
  ## [Object introspection](#class_RakuAST::Doc::Declarator "go to top of document")[§](#Object_introspection "direct link")
  
  `RakuAST::Doc::Declarator` objects are typically created when parsing Raku Programming Language code that has objects with leading (`#|`) and trailing (`#=`) documentation on it. So most developers will only need to know how to introspect the objects created.
  
  ### [method WHEREFORE](#class_RakuAST::Doc::Declarator "go to top of document")[§](#method_WHEREFORE "direct link")
  
  ```raku
  say "attached to a $declarator.WHEREFORE.^name() object";
  
  ```
  
  Returns the object for which this object contains the declarator documentation.
  
  ### [method leading](#class_RakuAST::Doc::Declarator "go to top of document")[§](#method_leading "direct link")
  
  ```raku
  .say for $declarator.leading;
  
  ```
  
  Returns the lines of the leading declarator documentation (one for each line with `#|` if the object was created from parsing Raku source code.
  
  ### [method trailing](#class_RakuAST::Doc::Declarator "go to top of document")[§](#method_trailing "direct link")
  
  ```raku
  .say for $declarator.trailing;
  
  ```
  
  Returns the lines of the trailing declarator documentation (one for each line with `#=` if the object was created from parsing Raku source code.
  
  ### [method raku](#class_RakuAST::Doc::Declarator "go to top of document")[§](#method_raku "direct link")
  
  ```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 [`RakuAST`](/type/RakuAST) calls.
  
  # [Object creation](#class_RakuAST::Doc::Declarator "go to top of document")[§](#Object_creation "direct link")
  
  One seldom creates `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 `RakuAST::Doc::Declarator` object.
  
  ## [method new](#class_RakuAST::Doc::Declarator "go to top of document")[§](#method_new "direct link")
  
  ```raku
  method new(
    Str:D :$WHEREFORE,  # the associated RakuAST object
          :@leading,    # leading lines of documentation
          :@trailing    # trailing lines of documentation
  )
  
  ```
  
  The `new` method can be called to create a new `RakuAST::Doc::Declarator` object. It only takes named arguments.
  
  ```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")
  );
  
  ```
  
  Note that the leading and trailing documentation may contain any left margin whitespace.
  
  ### [:WHEREFORE](#class_RakuAST::Doc::Declarator "go to top of document")[§](#:WHEREFORE "direct link")
  
  The [`RakuAST`](/type/RakuAST) object for which this declarator contains the documentation.
  
  ### [:leading](#class_RakuAST::Doc::Declarator "go to top of document")[§](#:leading "direct link")
  
  A [`Positional`](/type/Positional) with the lines of leading documentation strings.
  
  ### [:trailing](#class_RakuAST::Doc::Declarator "go to top of document")[§](#:trailing "direct link")
  
  A [`Positional`](/type/Positional) with the lines of trailing documentation strings.
  
  # [Object modification](#class_RakuAST::Doc::Declarator "go to top of document")[§](#Object_modification "direct link")
  
  ## [method set-WHEREFORE](#class_RakuAST::Doc::Declarator "go to top of document")[§](#method_set-WHEREFORE "direct link")
  
  ```raku
  $declarator.set-WHEREFORE($object);
  
  ```
  
  Set the object for which the `RakuAST::Doc::Declarator` object contains the documentation.
  
  ## [method set-leading](#class_RakuAST::Doc::Declarator "go to top of document")[§](#method_set-leading "direct link")
  
  ```raku
  $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.
  
  ## [method add-leading](#class_RakuAST::Doc::Declarator "go to top of document")[§](#method_add-leading "direct link")
  
  ```raku
  $declarator.add-leading("additional");
  
  ```
  
  Add a line to the leading documentation.
  
  ## [method set-trailing](#class_RakuAST::Doc::Declarator "go to top of document")[§](#method_set-trailing "direct link")
  
  ```raku
  $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.
  
  ## [method add-trailing](#class_RakuAST::Doc::Declarator "go to top of document")[§](#method_add-trailing "direct link")
  
  ```raku
  $declarator.add-trailing("additional");
  
  ```
  
  Add a line to the trailing documentation.
  