improve Optionals documentation and annotations