Added documentation, rearranged exclusion logic in caliper.cc

[apthorpe]

While working through the example code, I added Doxygen comments to caliper.cc and made several minor changes (rearranged exclusion logic, etc.). I don't believe there's any change in behavior regarding how the target file is modified but the diagnostic messages from std::cerr may differ slightly.