Pod6 Format

In Documentable, the documentation units are pod blocks. Each and every one of this pod block, is represented by a Documentable::Primary object. You could write this pod blocks in a lot of ways, so it would be hard to detect some needed data to generate an "useful" site. For this reason, you need to follow some basic requirements when writing documentation.

Inline metadata

You need to specify three different values for each pod block:

• kind: this value will be used to categorize the documentation block in menus (see Kind).

• subkind: more specific categorization. I recommend you to use values from Documentable::Heading::Grammar.

• category: submenu categorization. You will find some big menus corresponding to kinds, and inside each kind, there will be as many menus as different values for category. Note: you need to specify these values in the configuration file.

Example: if you have a class that you want to document, you would write the pod6 file as:

=begin pod :kind("Type") :subkind("class") :category("processing")
 
(...)
 
=end pod
 

Main headers

You must always specify a =TITLE and =SUBTITLE element.

• The content of this element, if kind is set to "type", will be used to set the name of the Documentable::Primary object. So, if you are documenting a type, you will need to write the title as follows:

  =begin pod
  =TITLE class Your::Class 
   
  'Your::Class' will be considered as name!
   
  =TITLE role Your::Role 
   
  'Your::Role' will be considered as name!
   
  =TITLE enum YourEnum 
   
  'YourEnum' will be considered as name!
  =end pod

  If it's not a type, then the full content of this element will be considered as name.

• =SUBTITLE element will be used as $summary attribute in Documentable::Primary.

And that's all, at the end, all your pod blocks should be something like:

=begin pod :kind(<kind>) :subkind(<subkind>) :category(<category>)
 
=TITLE Something 
 
=SUBTITLE Minimal description of Something 
 
=end pod
 

Multi-class file support

Sometimes is a pain to create a new file for every class, role or enum you want to document. Even sometimes, you have in the same code file an enum, some related exceptions, and who knows more, so the possibility to write all its documentation in the same file looks like quite useful. You are lucky! With Documentable you can do that!.

You only need to write more than one pod block in the same file (following the previous rules). For instance, let's document two different types: (the following code is in the same file)

=begin pod :kind("type") :subkind("class") :category("destruction")
 
=TITLE class Ultra::Weapon 
 
=SUBTITLE Destruction weapon 
 
=end pod
 
=begin pod :kind("type") :subkind("role") :category("exception")
 
=TITLE role X::IO 
 
=SUBTITLE IO related 
 
=end pod