add doc comments
make optionals-to-null comparision explicit