Architecture: How to define pins for a new board?

As I work upon the ESP8266 port, the time has come to provide some attention on the GPIO mechanism. When one defines a new board, one creates a Python script with the board name under /boards. It appears that within this script, we can define a variable called devices as well as define a function called get_pins(). What I am hoping I can get is some boot strap information on these. In return, I'll write up a users guide for those who may follow. Let's start with get_pins. What is that supposed to return when called?