docs: use annotations

docs/index.md

@@ -13,14 +13,14 @@ You can log a message by simply streaming things to `LOG`(<a particular
 #include <glog/logging.h>
 
 int main(int argc, char* argv[]) {
-    // Initialize Google’s logging library.
-    google::InitGoogleLogging(argv[0]);
-
-    // ...
-    LOG(INFO) << "Found " << num_cookies << " cookies";
+    google::InitGoogleLogging(argv[0]); // (1)!
+    LOG(INFO) << "Found " << num_cookies << " cookies"; // (2)!
 }
 ```
 
+1. Initialize the Google Logging Library
+2. Log a message with informational severity
+
 The library can be installed using various [package managers](packages.md) or
 compiled [from source](build.md). For a detailed overview of glog features and
 their usage, please refer to the [user guide](logging.md).

docs/logging.md

@@ -253,11 +253,13 @@ used as follows:
 
 ``` cpp
 if (VLOG_IS_ON(2)) {
-    // do some logging preparation and logging
-    // that can’t be accomplished with just VLOG(2) << ...;
+    // (1)
 }
 ```
 
+1. Here we can perform some logging preparation and logging that can’t be
+   accomplished with just `#!cpp VLOG(2) << "message ...";`
+
 Verbose level condition macros `VLOG_IF`, `VLOG_EVERY_N` and `VLOG_IF_EVERY_N`
 behave analogous to `LOG_IF`, `LOG_EVERY_N`, `LOG_IF_EVERY_N`, but accept a
 numeric verbosity level as opposed to a severity level.