fully finalized with docs and examples