Knowing the system

This is a hard question that I will try to answer the best I can. I will not talk about specific behaviors because that is described in the API documentation at the README. Instead, I will give you an idea of what's happening under the hoods and I will link the parts where you can get more technical information.

The process is split in three steps:

1. Cache the collection

This is quite simple: we take the whole pod collection and precompile it to bytecode using the Pod::To::Cached module, made by @finanalyst. Why we need to precompile them? Because in the old system they were precompiled up to 3 different times and that was quite time consuming. Now, we only do that once, at the beginning, so every operation related to pods made later will be faster.

2. Processing the collection

This is the hardest part of the process so pay attention. Before talk about how the collection is processed you need to understand what is a Perl6::Documentable object and what it represents.

A Perl6::Documentable object is whatever piece of Perl 6 that is documented. Ok, this definition is a little vague, but this concept is quite hard to explain so, instead, let's see what kind of Perl6::Documentable objects you can find in the pod collection:

2.1 Completed Perl6::Documentable objects

These are the first ones generated. They represent a whole pod file, like this one. So, if they represent an entire pod file, there should be as many of these objects as pod files in the collection, right? Exactly! At this moment there is around 392 of these files.

But how are they processed? That responsibility is done by process-pod-source in Perl6::Documentable::Registry (we'll see later what that thingy is). That method saves some information about where that pod file is stored, its pod content, etc. You can see what's actually stored here. All that information is stored inside the Perl6::Documentable object and will be highly used in the next steps of the process.

2.2 Perl6::Documentable objects related to definitions

These ones are the most confusing because of the rules followed to find them. First we need to know what a definition is: it's a piece of a pod that describes some behavior of an element in Perl 6. For instance: a method, a trait, an infix operator, etc.

How are these definitions written? Using headings. They are something like this in pod syntax: =head2 awesome. Right, but all headings found in the pod files are considered definitions? No, only a subset of them. The ones which follow this set of rules: (n is number from 1 to 6)

• First type: =headn The Foo Infix or =headn The C<Foo> Infix. Examples: 1, 2.
• Second type: =headn Infix Foo or =headn Infix C<Foo>. Examples 1.
• Third type: =headn trait Infix Foo2. Example 1

But, all values are valid? If I type =head2 The Luffy's Ship, that will be also indexed? You are lucky, because only some values are accepted. Infix does not have any constraints but Foo has to be one of the followings:

infix prefix postfix circumfix postcircumfix listop sub method term routine trait 
submethod constant variable twigil declarator quote

And if I want to index something really important that does not match any of the previous cases? Well, in that case, you can use the last type of definition: the unambiguous one. That definitions are something like this: headn X<something|random> where you can type whatever you want inside the <>. It will indexed no matter what's inside.

All this work is first made by parse-definition-header and classify-index in find-definitions.

2.3 Perl6::Documentable objects related to References

These are the last ones! These ones correspond to X<> elements. Each and every X<> element is represented by at least one Perl6::Documentable object. I have said "at least" because you can have references like this one X<sth|foo;foo2>, where foo and foo2 are two different references so that one would be represented by two objects: one representing X<sth|foo> and another representing X<sth|foo2>.

This work is done by find-references and register-reference.

Now we know all kinds of Perl6::Documentable objects, but how we manage all of them? That's where Perl6::Documentable::Registry comes in. That class stores all of this objects and provides you with functions to work with them: as lookup or grouped-by.

And that's all about Perl6::Documentable objects. I know is a lot but when you think about it is easy to get the gist of it.

3. Use the data!

Now that we have all pods processed and classified, it's time to generate HTML and indexes. That will be covered in another post because this is already quite long.