doc: improve programmers guide

Fix grammar, typos, formatting and markup issues.

Also correct some inaccurate API names, examples, section hierarchy and
wording that could mislead readers.

Signed-off-by: Nandini Persad <nandinipersad361@gmail.com>
Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>