[perl #40124] [TODO] Document HLL mappings

# New Ticket Created by Will Coleda
# Please include the string: [perl #40124]
# in the subject line of all future correspondence about this issue.
# <URL: http://rt.perl.org/rt3/Ticket/Display.html?id=40124 >

The purpose of each of the various HLL mappings should be documented;
that is, when you specify a mapping, in which cases is this defined
to do something. Additionally, what are the restrictions on each type
specification (e.g.: must "does array" vs. "extend array"?
restrictions on internal implementations? etc.).

For example : {{{

If you map to Float, then:

...

joe(1.2)

.sub joe
.param pmc number
...

Will use the mapped type instead of the core type Float when
autoboxing the 1.2 into a PMC.

}}}

As a starting point, here are the current parrot classes that are
being mapped either declaratively in the PMC or the at compile time
via the .HLL_map syntax.

Array
BigInt
Boolean
Closure
Complex
Coroutine
Exception
FixedPMCArray
Float
Hash
Integer
LexPad
NameSpace
None
OrderedHash
ResizablePMCArray
String
Sub
Undef

Knowing when these are used and what the restrictions on each of
those cases are will help HLL authors know when and how they should
be overriding them. (Or when not to bother implementing them because
they have no effect.)

--
Will "Coke" Coleda
wi...@coleda.com