commit 3cb23f1ff54e5ee37b761fdcbb832f69ee956d55
author G. Branden Robinson <Branden.Robinson@data61.csiro.au> Thu Oct 10 14:33:46 2019 +1100
committer G. Branden Robinson <Branden.Robinson@data61.csiro.au> Tue Nov 05 12:35:30 2019 +1100
tree d5f0734eccb0ff771e2361276eb2872a9fa4b1d1
parent d7be11ef70788b8f50232b5568088903077c5fae

sel4bench.h: update documentation and style

* Expand documentation of `sel4bench_enable_counters()`.
* Document `sel4bench_get_num_counter_chunks()`.
* Add missing @param and @return notations.
* Consistently use plurals in the strings for generic event names.
* Use Markdown backticks for literals (e.g., symbol names).
* Keep @param and @return descriptions terse (they should be noun
  phrases appropriate for tool tips).  Elaborations go in the function
  description.
* Don't abbreviate `sel4bench_init()` and `sel4bench_destroy()` as
  `_init()` and `_destroy()`, respectively.  Use the full names.
* Move documentation of constraint on number of counters to
  `sel4bench_get_num_counters()`, instead of duplicating it in two other
  functions.
* Emphasise that the cycle counter is not a performance counter.
* Clarify reference to ARM1136 platform, a.k.a. "kzm".

Flag open questions:
* Should some of these prototypes and constant objects be moved to a
  "private" header file?

Minor style issues:
* Perform minor wordsmithing.
* Use hyphens more idiomatically.
* Wrap lines at 80 columns.
* Use two spaces between sentences for readability.