txt: ## declaratortarget.md
  class RakuAST::Doc::DeclaratorTarget
  
  Provide leading/trailing doc functionality
  
  ```raku
  role RakuAST::Doc::DeclaratorTarget { }
  ```
  
  The `RakuAST::Doc::DeclaratorTarget` role is done by objects that support leading and trailing documentation.
  
  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::DeclaratorTarget "go to top of document")[§](#Object_introspection "direct link")
  
  Objects doing the `RakuAST::Doc::DeclaratorTarget` role are typically created when parsing Raku Programming Language code for objects that allow leading (`#|`) and trailing (`#=`) documentation on them. So most developers will only need to know how to introspect the objects created.
  
  ### [method WHY](#class_RakuAST::Doc::DeclaratorTarget "go to top of document")[§](#method_WHY "direct link")
  
  ```raku
  with $target.WHY {
      say "leading: $_.leading()";
      say "trailing: $_.trailing()";
  }
  
  ```
  
  Returns the [`RakuAST::Doc::Declarator`](/type/RakuAST/Doc/Declarator) object containing the declarator documentation, if any.
  
  # [Object creation](#class_RakuAST::Doc::DeclaratorTarget "go to top of document")[§](#Object_creation "direct link")
  
  Each object doing the `RakuAST::Doc::DeclaratorTarget` role has its own why of creation. So there's nothing general that can be said about it here.
  
  # [Object modification](#class_RakuAST::Doc::DeclaratorTarget "go to top of document")[§](#Object_modification "direct link")
  
  ## [method set-WHY](#class_RakuAST::Doc::DeclaratorTarget "go to top of document")[§](#method_set-WHY "direct link")
  
  ```raku
  $target.set-WHY($declarator);
  
  ```
  
  Set the [`RakuAST::Doc::Declarator`](/type/RakuAST/Doc/Declarator) object to be associated.
  
  ## [method cut-WHY](#class_RakuAST::Doc::DeclaratorTarget "go to top of document")[§](#method_cut-WHY "direct link")
  
  ```raku
  my $WHY := $target.cut-WHY;
  
  ```
  
  Removes the [`RakuAST::Doc::Declarator`](/type/RakuAST/Doc/Declarator) object, if any. Intended to be used when deparsing / stringification to prevent an infinite loop because the [`RakuAST::Doc::Declarator`](/type/RakuAST/Doc/Declarator) object points to its target, and the other way around. Usually called on a clone of the original target.
  
  ## [method set-leading](#class_RakuAST::Doc::DeclaratorTarget "go to top of document")[§](#method_set-leading "direct link")
  
  ```raku
  $target.set-leading;  # reset
  $target.set-leading("foo", "bar");
  
  ```
  
  Set the leading documentation. If no arguments are specified, reset to not having any leading documentation. Creates a [`RakuAST::Doc::Declarator`](/type/RakuAST/Doc/Declarator) object and sets it in the `.WHY` if there wasn't one already.
  
  ## [method add-leading](#class_RakuAST::Doc::DeclaratorTarget "go to top of document")[§](#method_add-leading "direct link")
  
  ```raku
  $target.add-leading("additional");
  
  ```
  
  Add a line to the leading documentation. Creates a [`RakuAST::Doc::Declarator`](/type/RakuAST/Doc/Declarator) object and sets it in the `.WHY` if there wasn't one already.
  
  ## [method set-trailing](#class_RakuAST::Doc::DeclaratorTarget "go to top of document")[§](#method_set-trailing "direct link")
  
  ```raku
  $target.set-trailing;  # reset
  $target.set-trailing("foo", "bar");
  
  ```
  
  Set the trailing documentation. If no arguments are specified, reset to not having any trailing documentation. Creates a [`RakuAST::Doc::Declarator`](/type/RakuAST/Doc/Declarator) object and sets it in the `.WHY` if there wasn't one already.
  
  ## [method add-trailing](#class_RakuAST::Doc::DeclaratorTarget "go to top of document")[§](#method_add-trailing "direct link")
  
  ```raku
  $target.add-trailing("additional");
  
  ```
  
  Add a line to the trailing documentation. Creates a [`RakuAST::Doc::Declarator`](/type/RakuAST/Doc/Declarator) object and sets it in the `.WHY` if there wasn't one already.
  