class Documentable::Primary

Represents a self-contained Raku documentation element.

Table of Contents
1	Methods
1.1	method new
1.2	method filename
1.3	method summary
1.4	method url
1.5	method defs
1.6	method refs
1.7	method check-pod
1.8	method parse-definition-header
1.9	method find-definitions
1.10	method find-references
2	Type Graph
3	Routines supplied by class Documentable
3.1	(Documentable) submethod BUILD
3.2	(Documentable) method name
3.3	(Documentable) method kind
3.4	(Documentable) method pod
3.5	(Documentable) method subkinds
3.6	(Documentable) method categories
3.7	(Documentable) method english-list

class Documentable::Primary {}

An instance of this object is used to represent every pod block found.

Methods

method new

Defined as

method new(Str :$filename!, :$pod!)

$pod must follow this format:

=begin pod :kind("<kind>") :subkind("<subkind>") :category("<category>")
 
=TITLE title 
 
=SUBTITLE subtitle 
 
(...)
 
=end pod

If at least one of these elements is missing, a exception will be thrown.

$filename is the name of the file containing the pod. This attribute is useful because several pods can be present in the same file, at the same time.

method filename

Defined as

method filename()

Returns the value of $!filename. It's the filename where the pod block came from.

method summary

Defined as

method summary()

Returns $!summary. This value is obtained using the =SUBTITLE pod element.

method url

Defined as

method url()

Returns the following string: /$!kind.Str/$filename. So, if you have a $pod block with $kind set to Kind::Language, stored in a file called lang.pod6, its url will be /language/lang.

If $kind is equal to Kind::Type, instead of $filename, $name will be taken (to avoid problems with multi-type definitions in a single file).

method defs

Defined as

method defs()

Returns @.defs. @.defs is an array containing all Documentable::Secondary objects found in the $.pod.

method refs

Defined as

method refs()

Returns @.refs. @.refs is an array containing all Documentable::Index objects found in the $.pod.

method check-pod

Defined as

method check-pod($pod, $filename?)

Check if a pod block (=begin pod =end pod) follows the specified format. It checks for the existence of a =TITLE and =SUBTITLE elements and the three metadata values.

method parse-definition-header

Defined as

method parse-definition-header(Pod::Heading :$heading --> Hash)

This method takes a Pod::Heading element and returns its metadata in a Hash object.

This returned Hash follow this format:

%(
    name       => ...
    kind       => ...
    subkinds   => ...
    categories => ...
)

For this to happen, the Pod::Heading object must verify one of this two conditions:

Must follow the format:
```
=headn X<foo|bar> 
```
Where n is a number from 1 to 6. In this case, subkinds and categories keys are set to the meta part of X<>, if possible. kind key is set to Kind::Syntax and name will be set to the second element of the meta part, or to the first one if there's only one.
Returns a non-empty match with Documentable::Heading::Grammar.

That means, if we have the following heading:
```
=head2 The infix foo 
```
Then the string The infix foo will be passed to the grammar, which will use Documentable::Heading::Actions to set the returned Hash.

method find-definitions

Defined as

method find-definitions(:$pod, Int :$min-level = -1 --> Int)

This method initializes the attribute @.defs. It runs through the pod content and looks for valid headings. When a new definition is found, a Documentable::Secondary object is created with the result of calling parse-definition-header (if the result is non-empty) and self as origin.

$pod is populated with the pod section corresponding to that header and its subdefinitions (all valid headers with a greater level until one with the same or lower level is found).

For instance, if we found the following pod section:

=head3 header 
 
Some text
 
=head4 header with a greater level! 
 
More text
 
=head3 another header with the same level!

In this case, $pod will be set to:

=head3 header 
 
Some text
 
=head4 header with a greater level! 
 
More text

method find-references

Defined as

method find-references(:$pod)

Similar to find-definitions. It runs through the pod recursively finding all X<> elements.

The behavior of X<> elements is being discussed here: https://github.com/Raku/doc/issues/1410. Any feedback is welcomed.

Type Graph

Type relations for Documentable::Primary

Expand above chart

Routines supplied by class Documentable

Documentable::Primary inherits from class Documentable, which provides the following routines:

(Documentable) submethod BUILD

Defined as

submethod BUILD(:$!name, :$!kind!, :@!subkinds, :@!categories, :$!pod!)

Returns a Documentable object correctly initialized.

(Documentable) method name

Defined as

method name(--> Str)

Returns $!name. You must have in mind that this value is not unique, so there could be more than one Documentable instance with the same name.

(Documentable) method kind

Defined as

method kind(--> Kind)

Returns $!kind. See Kind to get more info.

(Documentable) method pod

Defined as

method pod(--> Pod::Block)

Returns $!pod. $!pod is the documentation represented by this object.

(Documentable) method subkinds

Defined as

method subkinds(-->Array[Str])

Returns @!subkinds.

(Documentable) method categories

Returns @!categories. If @!categories is not defined, @!subkinds will be returned instead.

(Documentable) method english-list

Defined as:

method english-list()

This is a helper method used to convert lists (@.subkinds) to an "english" format.

my $doc = Documentable.new(
    kind     => Kind::Type,
    subkinds => ["a", "b"],
    pod      => []
);
 
say $doc.english-list # OUTPUT: a and b␤»