improve the docs theory and exampels to reflect what is available in the library.
improve the docs theory and exampels to reflect what is available in the library.