improved documentation and serialization