From 415c81b1814140b0cf1774a846f16f6f2cf59ed3 Mon Sep 17 00:00:00 2001
From: Roland Conybeare <rconybeare@gmail.com>
Date: Fri, 6 Oct 2023 23:41:26 -0400
Subject: [PATCH] README: formatting + example

---
 README.md | 38 ++++++++++++++++++++++++++++++++------
 1 file changed, 32 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index c020ad6..b0500c4 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,52 @@
 # python bindings for c++ reflection library (xo-reflect)
 
-### build + install
+## build + install
 ```
 $ cd xo-pyreflect
 $ mkdir build
 $ cd build
 $ INSTALL_PREFIX=/usr/local  # or wherever you prefer, e.g. ~/local
-$ cmake -DCMAKE_MODULE_PATH=${INSTALL_PREFIX}/share/cmake -DCMAKE_PREFIX_PATH=${INSTALL_PREFIX} -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} ..
+$ cmake \
+    -DCMAKE_MODULE_PATH=${INSTALL_PREFIX}/share/cmake \
+    -DCMAKE_PREFIX_PATH=${INSTALL_PREFIX} \
+    -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} ..
 $ make
 $ make install
 ```
 
-### build for unit test coverage
+## build for unit test coverage
 ```
 $ cd xo-pyreflect
 $ mkdir build-ccov
 $ cd build-ccov
-$ cmake -DCMAKE_MODULE_PATH=${INSTALL_PREFIX}/share/cmake  -DCMAKE_PREFIX_PATH=${INSTALL_PREFIX} -DCODE_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug ..
+$ cmake \
+    -DCMAKE_MODULE_PATH=${INSTALL_PREFIX}/share/cmake \
+    -DCMAKE_PREFIX_PATH=${INSTALL_PREFIX} \
+    -DCODE_COVERAGE=ON \
+    -DCMAKE_BUILD_TYPE=Debug ..
 ```
 
-### LSP support
+## LSP (language server) support
+
+LSP looks for compile commands in the root of the source tree;
+while Cmake creates them in the root of its build directory.
+
 ```
 $ cd xo-pyreflect
-$ ln -s build/compile_commands.json  # lsp will look for compile_commands.json in the root of the source tree
+$ ln -s build/compile_commands.json  # supply compile commands to LSP
 ```
+
+## Examples
+
+Assumes `xo-pyreflect` installed to `~/local2/lib`
+
+```
+PYTHONPATH=~/local2/lib python
+>>> import pyreflect
+>>> dir(pyreflect)
+['SelfTagging', 'TaggedRcptr', 'TypeDescr', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__']
+>>> pyreflect.TypeDescr.print_reflected_types()
+<type_table_v[0]:>
+```
+
+Not /immediately/ interesting:  no reflected types in `pyreflect` itself