Update API doc for Alarm Definitions

Explain how Alarm Definitions work and how they generate Alarms with
examples

Updated Table of Contents which was way out of date

Change-Id: I23c5531b645a2262abef50828f435fb7b9499521
Merge "Update API doc for Alarm Definitions"