Update documentation

Signed-off-by: Emerson Knapp <[email protected]>

README.md

@@ -1,8 +1,19 @@
 # rcpputils: ROS 2 C++ Utilities
 
-`rcpputils` is a C++ API consisting of macros, functions, and data structures used through out the ROS 2 code base.
+`rcpputils` is a C++ API consisting of macros, functions, and data structures intended for use throughout the ROS 2 codebase
 
-The API is a combination of parts:
+This package currently contains:
+*   Clang thread safety annotation macros
 
-- Macros for clang compiler's thread safety analysis
-  - rcpputils/thread_safety_annotations.h
+## Clang Thread Safety Annotation Macros
+the `rcpputils/thread_safety_annotations.h` header provides macros for Clang's [Thread Safety Analysis](https://clang.llvm.org/docs/ThreadSafetyAnalysis.html) feature.
+
+The macros allow you to annotate your code, but expand to nothing when using a non-clang compiler, so they are safe for cross-platform use.
+
+To use thread safety annotation in your package (in the Clang build only), enable the `-Wthread-safety` compiler flag, and include the header
+
+```
+#include "rcpputils/thread_safety_annotations.h"
+```
+
+For example usage, see [the documentation of this feature](https://clang.llvm.org/docs/ThreadSafetyAnalysis.html) and the tests in `test/test_basic.cpp`

package.xml

@@ -3,7 +3,7 @@
 <package format="2">
   <name>rcpputils</name>
   <version>0.1.0</version>
-  <description>Package containing various utility types and functions for C++</description>
+  <description>Package containing utility code for C++. Currently only Clang thread safety annotation macros</description>
   <maintainer email="[email protected]">Emerson Knapp</maintainer>
   <license>Apache License 2.0</license>